[TEXT-170] Add String lookup for host names and IP addresses (#118)
Merge remote-tracking branch 'origin/master'.
diff --git a/pom.xml b/pom.xml
index 7b77ab9..d9322a7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -54,7 +54,7 @@
<commons.jacoco.version>0.8.4</commons.jacoco.version>
- <commons.javadoc.version>3.1.0</commons.javadoc.version>
+ <commons.javadoc.version>3.1.1</commons.javadoc.version>
<!-- generate report even if there are binary incompatible changes -->
<commons.japicmp.breakBuildOnBinaryIncompatibleModifications>false</commons.japicmp.breakBuildOnBinaryIncompatibleModifications>
diff --git a/src/main/java/org/apache/commons/text/AlphabetConverter.java b/src/main/java/org/apache/commons/text/AlphabetConverter.java
index 9449904..b210092 100644
--- a/src/main/java/org/apache/commons/text/AlphabetConverter.java
+++ b/src/main/java/org/apache/commons/text/AlphabetConverter.java
@@ -109,7 +109,7 @@
* Encode a given string.
*
* @param original the string to be encoded
- * @return the encoded string, {@code null} if the given string is null
+ * @return The encoded string, {@code null} if the given string is null
* @throws UnsupportedEncodingException if chars that are not supported are
* encountered
*/
@@ -148,7 +148,7 @@
*
* @param encoded a string that has been encoded using this
* AlphabetConverter
- * @return the decoded string, {@code null} if the given string is null
+ * @return The decoded string, {@code null} if the given string is null
* @throws UnsupportedEncodingException if unexpected characters that
* cannot be handled are encountered
*/
@@ -194,7 +194,7 @@
* for each character in the original
* alphabet.
*
- * @return the length of the encoded char
+ * @return The length of the encoded char
*/
public int getEncodedCharLength() {
return encodedLetterLength;
@@ -205,7 +205,7 @@
* string. Use to reconstruct converter from
* serialized map.
*
- * @return the original map
+ * @return The original map
*/
public Map<Integer, String> getOriginalToEncoded() {
return Collections.unmodifiableMap(originalToEncoded);
@@ -315,7 +315,7 @@
* Create a new converter from a map.
*
* @param originalToEncoded a map returned from getOriginalToEncoded()
- * @return the reconstructed AlphabetConverter
+ * @return The reconstructed AlphabetConverter
* @see AlphabetConverter#getOriginalToEncoded()
*/
public static AlphabetConverter createConverterFromMap(
@@ -354,7 +354,7 @@
* @param doNotEncode an array of chars to be encoded using the original
* alphabet - every char here must appear in
* both the previous params
- * @return the AlphabetConverter
+ * @return The AlphabetConverter
* @throws IllegalArgumentException if an AlphabetConverter cannot be
* constructed
*/
@@ -399,7 +399,7 @@
* @param doNotEncode an array of ints representing the chars to be encoded
* using the original alphabet - every char
* here must appear in both the previous params
- * @return the AlphabetConverter
+ * @return The AlphabetConverter
* @throws IllegalArgumentException if an AlphabetConverter cannot be
* constructed
*/
diff --git a/src/main/java/org/apache/commons/text/Builder.java b/src/main/java/org/apache/commons/text/Builder.java
index c2c435c..a511b2b 100644
--- a/src/main/java/org/apache/commons/text/Builder.java
+++ b/src/main/java/org/apache/commons/text/Builder.java
@@ -82,7 +82,7 @@
* Returns a reference to the object being constructed or result being
* calculated by the builder.
*
- * @return the object constructed or result calculated by the builder.
+ * @return The object constructed or result calculated by the builder.
*/
T build();
}
diff --git a/src/main/java/org/apache/commons/text/CompositeFormat.java b/src/main/java/org/apache/commons/text/CompositeFormat.java
index bbe5754..8f1e116 100644
--- a/src/main/java/org/apache/commons/text/CompositeFormat.java
+++ b/src/main/java/org/apache/commons/text/CompositeFormat.java
@@ -76,7 +76,7 @@
* @param pos the ParsePosition containing the position to parse from, will
* be updated according to parsing success (index) or failure
* (error index)
- * @return the parsed Object
+ * @return The parsed Object
* @see Format#parseObject(String, ParsePosition)
*/
@Override
diff --git a/src/main/java/org/apache/commons/text/FormattableUtils.java b/src/main/java/org/apache/commons/text/FormattableUtils.java
index a3eb153..242a82a 100644
--- a/src/main/java/org/apache/commons/text/FormattableUtils.java
+++ b/src/main/java/org/apache/commons/text/FormattableUtils.java
@@ -56,7 +56,7 @@
* {@code Formattable}.
*
* @param formattable the instance to convert to a string, not null
- * @return the resulting string, not null
+ * @return The resulting string, not null
*/
public static String toString(final Formattable formattable) {
return String.format(SIMPLEST_FORMAT, formattable);
@@ -72,7 +72,7 @@
* @param flags the flags for formatting, see {@code Formattable}
* @param width the width of the output, see {@code Formattable}
* @param precision the precision of the output, see {@code Formattable}
- * @return the {@code formatter} instance, not null
+ * @return The {@code formatter} instance, not null
*/
public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
final int precision) {
@@ -89,7 +89,7 @@
* @param width the width of the output, see {@code Formattable}
* @param precision the precision of the output, see {@code Formattable}
* @param padChar the pad character to use
- * @return the {@code formatter} instance, not null
+ * @return The {@code formatter} instance, not null
*/
public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
final int precision, final char padChar) {
@@ -107,7 +107,7 @@
* @param precision the precision of the output, see {@code Formattable}
* @param ellipsis the ellipsis to use when precision dictates truncation, null or
* empty causes a hard truncation
- * @return the {@code formatter} instance, not null
+ * @return The {@code formatter} instance, not null
*/
public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
final int precision, final CharSequence ellipsis) {
@@ -125,7 +125,7 @@
* @param padChar the pad character to use
* @param ellipsis the ellipsis to use when precision dictates truncation, null or
* empty causes a hard truncation
- * @return the {@code formatter} instance, not null
+ * @return The {@code formatter} instance, not null
*/
public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
final int precision, final char padChar, final CharSequence ellipsis) {
diff --git a/src/main/java/org/apache/commons/text/RandomStringGenerator.java b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
index 3e4a54c..b927508 100644
--- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
+++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
@@ -114,7 +114,7 @@
* the minimum value allowed
* @param maxInclusive
* the maximum value allowed
- * @return the random number.
+ * @return The random number.
*/
private int generateRandomNumber(final int minInclusive, final int maxInclusive) {
if (random != null) {
@@ -128,7 +128,7 @@
* or the user-supplied source of randomness.
*
* @param characterList predefined char list.
- * @return the random number.
+ * @return The random number.
*/
private int generateRandomNumber(final List<Character> characterList) {
final int listSize = characterList.size();
@@ -157,7 +157,7 @@
*
* @param length
* the number of code points to generate
- * @return the generated string
+ * @return The generated string
* @throws IllegalArgumentException
* if {@code length < 0}
*/
@@ -214,7 +214,7 @@
* the minimum (inclusive) number of code points to generate
* @param maxLengthInclusive
* the maximum (inclusive) number of code points to generate
- * @return the generated string
+ * @return The generated string
* @throws IllegalArgumentException
* if {@code minLengthInclusive < 0}, or {@code maxLengthInclusive < minLengthInclusive}
* @see RandomStringGenerator#generate(int)
@@ -455,7 +455,7 @@
/**
* <p>Builds the {@code RandomStringGenerator} using the properties specified.</p>
- * @return the configured {@code RandomStringGenerator}
+ * @return The configured {@code RandomStringGenerator}
*/
@Override
public RandomStringGenerator build() {
diff --git a/src/main/java/org/apache/commons/text/StrBuilder.java b/src/main/java/org/apache/commons/text/StrBuilder.java
index dd6ae53..44cd765 100644
--- a/src/main/java/org/apache/commons/text/StrBuilder.java
+++ b/src/main/java/org/apache/commons/text/StrBuilder.java
@@ -132,7 +132,7 @@
/**
* Gets the text to be appended when a new line is added.
*
- * @return the new line text, null means use system default
+ * @return The new line text, null means use system default
*/
public String getNewLineText() {
return newLine;
@@ -153,7 +153,7 @@
/**
* Gets the text to be appended when null is added.
*
- * @return the null text, null means no append
+ * @return The null text, null means no append
*/
public String getNullText() {
return nullText;
@@ -177,7 +177,7 @@
/**
* Gets the length of the string builder.
*
- * @return the length
+ * @return The length
*/
@Override
public int length() {
@@ -214,7 +214,7 @@
/**
* Gets the current size of the internal character array buffer.
*
- * @return the capacity
+ * @return The capacity
*/
public int capacity() {
return buffer.length;
@@ -256,7 +256,7 @@
* This method is the same as {@link #length()} and is provided to match the
* API of Collections.
*
- * @return the length
+ * @return The length
*/
public int size() {
return size;
@@ -297,7 +297,7 @@
* @see #setCharAt(int, char)
* @see #deleteCharAt(int)
* @param index the index to retrieve, must be valid
- * @return the character at the index
+ * @return The character at the index
* @throws IndexOutOfBoundsException if the index is invalid
*/
@Override
@@ -383,7 +383,7 @@
* Copies the character array into the specified array.
*
* @param destination the destination array, null will cause an array to be created
- * @return the input array, unless that was null or too small
+ * @return The input array, unless that was null or too small
*/
public char[] getChars(char[] destination) {
final int len = length();
@@ -426,7 +426,7 @@
* character buffer without making extra copies.
*
* @param readable object to read from
- * @return the number of characters read
+ * @return The number of characters read
* @throws IOException if an I/O error occurs
*
* @see #appendTo(Appendable)
@@ -2221,7 +2221,7 @@
* Extracts a portion of this string builder as a string.
*
* @param start the start index, inclusive, must be valid
- * @return the new string
+ * @return The new string
* @throws IndexOutOfBoundsException if the index is invalid
*/
public String substring(final int start) {
@@ -2238,7 +2238,7 @@
* @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
+ * @return The new string
* @throws IndexOutOfBoundsException if the index is invalid
*/
public String substring(final int startIndex, int endIndex) {
@@ -2256,7 +2256,7 @@
* length requested.
*
* @param length the number of characters to extract, negative returns empty string
- * @return the new string
+ * @return The new string
*/
public String leftString(final int length) {
if (length <= 0) {
@@ -2278,7 +2278,7 @@
* length requested.
*
* @param length the number of characters to extract, negative returns empty string
- * @return the new string
+ * @return The new string
*/
public String rightString(final int length) {
if (length <= 0) {
@@ -2304,7 +2304,7 @@
*
* @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
+ * @return The new string
*/
public String midString(int index, final int length) {
if (index < 0) {
@@ -2366,7 +2366,7 @@
* Searches the string builder to find the first reference to the specified char.
*
* @param ch the character to find
- * @return the first index of the character, or -1 if not found
+ * @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch) {
return indexOf(ch, 0);
@@ -2377,7 +2377,7 @@
*
* @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
+ * @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2399,7 +2399,7 @@
* Note that a null input string will return -1, whereas the JDK throws an exception.
*
* @param str the string to find, null returns -1
- * @return the first index of the string, or -1 if not found
+ * @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str) {
return indexOf(str, 0);
@@ -2413,7 +2413,7 @@
*
* @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
+ * @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2452,7 +2452,7 @@
* followed by a number.
*
* @param matcher the matcher to use, null returns -1
- * @return the first index matched, or -1 if not found
+ * @return The first index matched, or -1 if not found
*/
public int indexOf(final StrMatcher matcher) {
return indexOf(matcher, 0);
@@ -2468,7 +2468,7 @@
*
* @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
+ * @return The first index matched, or -1 if not found
*/
public int indexOf(final StrMatcher matcher, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2490,7 +2490,7 @@
* Searches the string builder to find the last reference to the specified char.
*
* @param ch the character to find
- * @return the last index of the character, or -1 if not found
+ * @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch) {
return lastIndexOf(ch, size - 1);
@@ -2501,7 +2501,7 @@
*
* @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
+ * @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2522,7 +2522,7 @@
* Note that a null input string will return -1, whereas the JDK throws an exception.
*
* @param str the string to find, null returns -1
- * @return the last index of the string, or -1 if not found
+ * @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str) {
return lastIndexOf(str, size - 1);
@@ -2536,7 +2536,7 @@
*
* @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
+ * @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2573,7 +2573,7 @@
* followed by a number.
*
* @param matcher the matcher to use, null returns -1
- * @return the last index matched, or -1 if not found
+ * @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StrMatcher matcher) {
return lastIndexOf(matcher, size);
@@ -2589,7 +2589,7 @@
*
* @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
+ * @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StrMatcher matcher, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2806,7 +2806,7 @@
* Note that unlike StringBuffer, the string version returned is
* independent of the string builder.
*
- * @return the builder as a String
+ * @return The builder as a String
*/
@Override
public String toString() {
@@ -2817,7 +2817,7 @@
* Gets a StringBuffer version of the string builder, creating a
* new instance each time the method is called.
*
- * @return the builder as a StringBuffer
+ * @return The builder as a StringBuffer
*/
public StringBuffer toStringBuffer() {
return new StringBuffer(size).append(buffer, 0, size);
@@ -2827,7 +2827,7 @@
* Gets a StringBuilder version of the string builder, creating a
* new instance each time the method is called.
*
- * @return the builder as a StringBuilder
+ * @return The builder as a StringBuilder
*/
public StringBuilder toStringBuilder() {
return new StringBuilder(size).append(buffer, 0, size);
@@ -2835,7 +2835,7 @@
/**
* Implement the {@link Builder} interface.
- * @return the builder as a String
+ * @return The builder as a String
* @see #toString()
*/
@Override
@@ -2850,7 +2850,7 @@
* @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
+ * @return The new string
* @throws IndexOutOfBoundsException if the index is invalid
*/
protected int validateRange(final int startIndex, int endIndex) {
diff --git a/src/main/java/org/apache/commons/text/StrLookup.java b/src/main/java/org/apache/commons/text/StrLookup.java
index b197e1d..0147232 100644
--- a/src/main/java/org/apache/commons/text/StrLookup.java
+++ b/src/main/java/org/apache/commons/text/StrLookup.java
@@ -136,7 +136,7 @@
* If the map is null, then null is returned. The map result object is converted to a string using toString().
*
* @param key the key to be looked up, may be null
- * @return the matching value, null if no match
+ * @return The matching value, null if no match
*/
@Override
public String lookup(final String key) {
diff --git a/src/main/java/org/apache/commons/text/StrMatcher.java b/src/main/java/org/apache/commons/text/StrMatcher.java
index 958dd8c..1629a4f 100644
--- a/src/main/java/org/apache/commons/text/StrMatcher.java
+++ b/src/main/java/org/apache/commons/text/StrMatcher.java
@@ -112,7 +112,7 @@
* Matches the same characters as StringTokenizer,
* namely space, tab, newline and form feed.
*
- * @return the split matcher
+ * @return The split matcher
*/
public static StrMatcher splitMatcher() {
return SPLIT_MATCHER;
@@ -121,7 +121,7 @@
/**
* Matches the String trim() whitespace characters.
*
- * @return the trim matcher
+ * @return The trim matcher
*/
public static StrMatcher trimMatcher() {
return TRIM_MATCHER;
@@ -249,7 +249,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index (exclusive) of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
public abstract int isMatch(char[] buffer, int pos, int bufferStart, int bufferEnd);
@@ -270,7 +270,7 @@
*
* @param buffer the text content to match against, do not change
* @param pos the starting position for the match, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
public int isMatch(final char[] buffer, final int pos) {
return isMatch(buffer, pos, 0, buffer.length);
@@ -302,7 +302,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -335,7 +335,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -368,7 +368,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
@Override
public int isMatch(final char[] buffer, int pos, final int bufferStart, final int bufferEnd) {
@@ -411,7 +411,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -439,7 +439,7 @@
* @param pos the starting position for the match, valid for buffer
* @param bufferStart the first active index in the buffer, valid for buffer
* @param bufferEnd the end index of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
diff --git a/src/main/java/org/apache/commons/text/StrSubstitutor.java b/src/main/java/org/apache/commons/text/StrSubstitutor.java
index d285991..63f0be1 100644
--- a/src/main/java/org/apache/commons/text/StrSubstitutor.java
+++ b/src/main/java/org/apache/commons/text/StrSubstitutor.java
@@ -194,7 +194,7 @@
* @param <V> the type of the values in the map
* @param source the source text containing the variables to substitute, null returns null
* @param valueMap the map with the values, may be null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public static <V> String replace(final Object source, final Map<String, V> valueMap) {
return new StrSubstitutor(valueMap).replace(source);
@@ -210,7 +210,7 @@
* @param valueMap the map with the values, may be null
* @param prefix the prefix of variables, not null
* @param suffix the suffix of variables, not null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException if the prefix or suffix is null
*/
public static <V> String replace(final Object source,
@@ -226,7 +226,7 @@
*
* @param source the source text containing the variables to substitute, null returns null
* @param valueProperties the properties with values, may be null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public static String replace(final Object source, final Properties valueProperties) {
if (valueProperties == null) {
@@ -247,7 +247,7 @@
* their matching values from the system properties.
*
* @param source the source text containing the variables to substitute, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public static String replaceSystemProperties(final Object source) {
return new StrSubstitutor(StrLookup.systemPropertiesLookup()).replace(source);
@@ -404,7 +404,7 @@
* from the resolver using the given source string as a template.
*
* @param source the string to replace in, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final String source) {
if (source == null) {
@@ -427,7 +427,7 @@
* @param source the string to replace in, null returns null
* @param offset the start offset within the array, must be valid
* @param length the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final String source, final int offset, final int length) {
if (source == null) {
@@ -447,7 +447,7 @@
* The array is not altered by this method.
*
* @param source the character array to replace in, not altered, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final char[] source) {
if (source == null) {
@@ -469,7 +469,7 @@
* @param source the character array to replace in, not altered, null returns null
* @param offset the start offset within the array, must be valid
* @param length the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final char[] source, final int offset, final int length) {
if (source == null) {
@@ -487,7 +487,7 @@
* The buffer is not altered by this method.
*
* @param source the buffer to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final StringBuffer source) {
if (source == null) {
@@ -509,7 +509,7 @@
* @param source the buffer to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
* @param length the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final StringBuffer source, final int offset, final int length) {
if (source == null) {
@@ -526,7 +526,7 @@
* The source is not altered by this method.
*
* @param source the buffer to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final CharSequence source) {
if (source == null) {
@@ -546,7 +546,7 @@
* @param source the buffer to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
* @param length the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final CharSequence source, final int offset, final int length) {
if (source == null) {
@@ -564,7 +564,7 @@
* The builder is not altered by this method.
*
* @param source the builder to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final StrBuilder source) {
if (source == null) {
@@ -586,7 +586,7 @@
* @param source the builder to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
* @param length the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final StrBuilder source, final int offset, final int length) {
if (source == null) {
@@ -604,7 +604,7 @@
* converted to a string using <code>toString</code> and is not altered.
*
* @param source the source to replace in, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
*/
public String replace(final Object source) {
if (source == null) {
@@ -759,7 +759,7 @@
* @param offset the start offset within the builder, must be valid
* @param length the length within the builder to be processed, must be valid
* @param priorVariables the stack keeping track of the replaced variables, may be null
- * @return the length change that occurs, unless priorVariables is null when the int
+ * @return The length change that occurs, unless priorVariables is null when the int
* represents a boolean flag as to whether any change occurred.
*/
private int substitute(final StrBuilder buf, final int offset, final int length, List<String> priorVariables) {
@@ -941,7 +941,7 @@
* @param buf the buffer where the substitution is occurring, not null
* @param startPos the start position of the variable including the prefix, valid
* @param endPos the end position of the variable including the suffix, valid
- * @return the variable's value or <b>null</b> if the variable is unknown
+ * @return The variable's value or <b>null</b> if the variable is unknown
*/
protected String resolveVariable(final String variableName,
final StrBuilder buf,
@@ -959,7 +959,7 @@
/**
* Returns the escape character.
*
- * @return the character used for escaping variable references
+ * @return The character used for escaping variable references
*/
public char getEscapeChar() {
return this.escapeChar;
@@ -985,7 +985,7 @@
* start of a variable. This prefix is expressed in terms of a matcher
* allowing advanced prefix matches.
*
- * @return the prefix matcher in use
+ * @return The prefix matcher in use
*/
public StrMatcher getVariablePrefixMatcher() {
return prefixMatcher;
@@ -1046,7 +1046,7 @@
* end of a variable. This suffix is expressed in terms of a matcher
* allowing advanced suffix matches.
*
- * @return the suffix matcher in use
+ * @return The suffix matcher in use
*/
public StrMatcher getVariableSuffixMatcher() {
return suffixMatcher;
@@ -1109,7 +1109,7 @@
* <p>
* If it returns null, then the variable default value resolution is disabled.
*
- * @return the variable default value delimiter matcher in use, may be null
+ * @return The variable default value delimiter matcher in use, may be null
*/
public StrMatcher getValueDelimiterMatcher() {
return valueDelimiterMatcher;
@@ -1173,7 +1173,7 @@
/**
* Gets the VariableResolver that is used to lookup variables.
*
- * @return the VariableResolver
+ * @return The VariableResolver
*/
public StrLookup<?> getVariableResolver() {
return this.variableResolver;
@@ -1193,7 +1193,7 @@
/**
* Returns a flag whether substitution is done in variable names.
*
- * @return the substitution in variable names flag
+ * @return The substitution in variable names flag
*/
public boolean isEnableSubstitutionInVariables() {
return enableSubstitutionInVariables;
@@ -1229,7 +1229,7 @@
* Hi Douglas ${surname}
* </pre>
*
- * @return the substitution in variable values flag
+ * @return The substitution in variable values flag
*
* @since 1.2
*/
@@ -1252,7 +1252,7 @@
* Returns the flag controlling whether escapes are preserved during
* substitution.
*
- * @return the preserve escape flag
+ * @return The preserve escape flag
*/
public boolean isPreserveEscapes() {
return preserveEscapes;
diff --git a/src/main/java/org/apache/commons/text/StrTokenizer.java b/src/main/java/org/apache/commons/text/StrTokenizer.java
index 563ecb8..ed0255e 100644
--- a/src/main/java/org/apache/commons/text/StrTokenizer.java
+++ b/src/main/java/org/apache/commons/text/StrTokenizer.java
@@ -393,7 +393,7 @@
/**
* Gets the number of tokens found in the String.
*
- * @return the number of matched tokens
+ * @return The number of matched tokens
*/
public int size() {
checkTokenized();
@@ -405,7 +405,7 @@
* Equivalent to {@link #next()} except it returns null rather than
* throwing {@link NoSuchElementException} when no tokens remain.
*
- * @return the next sequential token, or null when no more tokens are found
+ * @return The next sequential token, or null when no more tokens are found
*/
public String nextToken() {
if (hasNext()) {
@@ -417,7 +417,7 @@
/**
* Gets the previous token from the String.
*
- * @return the previous sequential token, or null when no more tokens are found
+ * @return The previous sequential token, or null when no more tokens are found
*/
public String previousToken() {
if (hasPrevious()) {
@@ -429,7 +429,7 @@
/**
* Gets a copy of the full token list as an independent modifiable array.
*
- * @return the tokens as a String array
+ * @return The tokens as a String array
*/
public String[] getTokenArray() {
checkTokenized();
@@ -439,7 +439,7 @@
/**
* Gets a copy of the full token list as an independent modifiable list.
*
- * @return the tokens as a String array
+ * @return The tokens as a String array
*/
public List<String> getTokenList() {
checkTokenized();
@@ -514,7 +514,7 @@
/**
* Gets the next token.
*
- * @return the next String token
+ * @return The next String token
* @throws NoSuchElementException if there are no more elements
*/
@Override
@@ -528,7 +528,7 @@
/**
* Gets the index of the next token to return.
*
- * @return the next token index
+ * @return The next token index
*/
@Override
public int nextIndex() {
@@ -549,7 +549,7 @@
/**
* Gets the token previous to the last returned token.
*
- * @return the previous token
+ * @return The previous token
*/
@Override
public String previous() {
@@ -562,7 +562,7 @@
/**
* Gets the index of the previous token.
*
- * @return the previous token index
+ * @return The previous token index
*/
@Override
public int previousIndex() {
@@ -635,7 +635,7 @@
* @param srcChars the character array being tokenized, may be null
* @param offset the start position within the character array, must be valid
* @param count the number of characters to tokenize, must be valid
- * @return the modifiable list of String tokens, unmodifiable if null array or zero count
+ * @return The modifiable list of String tokens, unmodifiable if null array or zero count
*/
protected List<String> tokenize(final char[] srcChars, final int offset, final int count) {
if (srcChars == null || count == 0) {
@@ -684,7 +684,7 @@
* @param len the length of the character array being tokenized
* @param workArea a temporary work area
* @param tokenList the list of parsed tokens
- * @return the starting position of the next field (the character
+ * @return The starting position of the next field (the character
* immediately after the delimiter), or -1 if end of string found
*/
private int readNextToken(final char[] srcChars,
@@ -737,7 +737,7 @@
* @param tokenList the list of parsed tokens
* @param quoteStart the start position of the matched quote, 0 if no quoting
* @param quoteLen the length of the matched quote, 0 if no quoting
- * @return the starting position of the next field (the character
+ * @return The starting position of the next field (the character
* immediately after the delimiter, or if end of string found,
* then the length of string
*/
@@ -855,7 +855,7 @@
/**
* Gets the field delimiter matcher.
*
- * @return the delimiter matcher in use
+ * @return The delimiter matcher in use
*/
public StrMatcher getDelimiterMatcher() {
return this.delimMatcher;
@@ -907,7 +907,7 @@
* This enables delimiters to be entered as data.
* The default value is '"' (double quote).
*
- * @return the quote matcher in use
+ * @return The quote matcher in use
*/
public StrMatcher getQuoteMatcher() {
return quoteMatcher;
@@ -951,7 +951,7 @@
* within a quoted region.
* The default value is not to ignore anything.
*
- * @return the ignored matcher in use
+ * @return The ignored matcher in use
*/
public StrMatcher getIgnoredMatcher() {
return ignoredMatcher;
@@ -995,7 +995,7 @@
* until the token or quote is found.
* The default value is not to trim anything.
*
- * @return the trimmer matcher in use
+ * @return The trimmer matcher in use
*/
public StrMatcher getTrimmerMatcher() {
return trimmerMatcher;
@@ -1067,7 +1067,7 @@
/**
* Gets the String content that the tokenizer is parsing.
*
- * @return the string content being parsed
+ * @return The string content being parsed
*/
public String getContent() {
if (chars == null) {
@@ -1114,7 +1114,7 @@
/**
* Gets the String content that the tokenizer is parsing.
*
- * @return the string content being parsed
+ * @return The string content being parsed
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/text/StringEscapeUtils.java b/src/main/java/org/apache/commons/text/StringEscapeUtils.java
index b183233..1b2bc5f 100644
--- a/src/main/java/org/apache/commons/text/StringEscapeUtils.java
+++ b/src/main/java/org/apache/commons/text/StringEscapeUtils.java
@@ -483,7 +483,7 @@
/**
* <p>Return the escaped string.</p>
*
- * @return the escaped string
+ * @return The escaped string
*/
@Override
public String toString() {
@@ -801,7 +801,7 @@
* <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.
*
* @param input the input CSV column String, may be null
- * @return the input String, enclosed in double quotes if the value contains a comma,
+ * @return The input String, enclosed in double quotes if the value contains a comma,
* newline or double quote, {@code null} if null string input
*/
public static final String escapeCsv(final String input) {
@@ -825,7 +825,7 @@
* <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.
*
* @param input the input CSV column String, may be null
- * @return the input String, with enclosing double quotes removed and embedded double
+ * @return The input String, with enclosing double quotes removed and embedded double
* quotes unescaped, {@code null} if null string input
*/
public static final String unescapeCsv(final String input) {
diff --git a/src/main/java/org/apache/commons/text/StringSubstitutor.java b/src/main/java/org/apache/commons/text/StringSubstitutor.java
index 6764fe6..99b9c7a 100644
--- a/src/main/java/org/apache/commons/text/StringSubstitutor.java
+++ b/src/main/java/org/apache/commons/text/StringSubstitutor.java
@@ -184,6 +184,14 @@
/**
* Creates a new instance using the interpolator string lookup
* {@link StringLookupFactory#interpolatorStringLookup()}.
+ * <p>
+ * This StringSubstitutor lets you perform substituions like:
+ * </p>
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace(
+ * "OS name: ${sys:os.name}, " +
+ * "3 + 4 = ${script:javascript:3 + 4}");
+ * </pre>
*
* @return a new instance using the interpolator string lookup.
* @see StringLookupFactory#interpolatorStringLookup()
@@ -202,7 +210,7 @@
* the source text containing the variables to substitute, null returns null
* @param valueMap
* the map with the values, may be null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if a variable is not found and enableUndefinedVariableException is true
*/
@@ -224,7 +232,7 @@
* the prefix of variables, not null
* @param suffix
* the suffix of variables, not null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if the prefix or suffix is null
* @throws IllegalArgumentException
@@ -243,7 +251,7 @@
* the source text containing the variables to substitute, null returns null
* @param valueProperties
* the properties with values, may be null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if a variable is not found and enableUndefinedVariableException is true
*/
@@ -267,7 +275,7 @@
*
* @param source
* the source text containing the variables to substitute, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if a variable is not found and enableUndefinedVariableException is true
*/
@@ -530,7 +538,7 @@
/**
* Returns the escape character.
*
- * @return the character used for escaping variable references
+ * @return The character used for escaping variable references
*/
public char getEscapeChar() {
return this.escapeChar;
@@ -541,7 +549,7 @@
/**
* Gets the StringLookup that is used to lookup variables.
*
- * @return the StringLookup
+ * @return The StringLookup
*/
public StringLookup getStringLookup() {
return this.variableResolver;
@@ -558,7 +566,7 @@
* <p>
* If it returns null, then the variable default value resolution is disabled.
*
- * @return the variable default value delimiter matcher in use, may be null
+ * @return The variable default value delimiter matcher in use, may be null
*/
public StringMatcher getValueDelimiterMatcher() {
return valueDelimiterMatcher;
@@ -572,7 +580,7 @@
* The variable prefix is the character or characters that identify the start of a variable. This prefix is
* expressed in terms of a matcher allowing advanced prefix matches.
*
- * @return the prefix matcher in use
+ * @return The prefix matcher in use
*/
public StringMatcher getVariablePrefixMatcher() {
return prefixMatcher;
@@ -586,7 +594,7 @@
* The variable suffix is the character or characters that identify the end of a variable. This suffix is expressed
* in terms of a matcher allowing advanced suffix matches.
*
- * @return the suffix matcher in use
+ * @return The suffix matcher in use
*/
public StringMatcher getVariableSuffixMatcher() {
return suffixMatcher;
@@ -611,7 +619,7 @@
* Hi Douglas ${surname}
* </pre>
*
- * @return the substitution in variable values flag
+ * @return The substitution in variable values flag
*/
public boolean isDisableSubstitutionInValues() {
return disableSubstitutionInValues;
@@ -622,7 +630,7 @@
/**
* Returns a flag whether substitution is done in variable names.
*
- * @return the substitution in variable names flag
+ * @return The substitution in variable names flag
*/
public boolean isEnableSubstitutionInVariables() {
return enableSubstitutionInVariables;
@@ -632,7 +640,7 @@
* Returns a flag whether exception can be thrown upon undefined
* variable.
*
- * @return the fail on undefined variable flag
+ * @return The fail on undefined variable flag
*/
public boolean isEnableUndefinedVariableException() {
return enableUndefinedVariableException;
@@ -641,7 +649,7 @@
/**
* Returns the flag controlling whether escapes are preserved during substitution.
*
- * @return the preserve escape flag
+ * @return The preserve escape flag
*/
public boolean isPreserveEscapes() {
return preserveEscapes;
@@ -654,7 +662,7 @@
*
* @param source
* the character array to replace in, not altered, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -680,7 +688,7 @@
* the start offset within the array, must be valid
* @param length
* the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -699,7 +707,7 @@
*
* @param source
* the buffer to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -723,7 +731,7 @@
* the start offset within the array, must be valid
* @param length
* the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -743,7 +751,7 @@
*
* @param source
* the source to replace in, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if a variable is not found and enableUndefinedVariableException is true
*/
@@ -763,7 +771,7 @@
*
* @param source
* the string to replace in, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -791,7 +799,7 @@
* the start offset within the array, must be valid
* @param length
* the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -813,7 +821,7 @@
*
* @param source
* the buffer to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -839,7 +847,7 @@
* the start offset within the array, must be valid
* @param length
* the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -859,7 +867,7 @@
*
* @param source
* the builder to use as a template, not changed, null returns null
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -885,7 +893,7 @@
* the start offset within the array, must be valid
* @param length
* the length within the array to be processed, must be valid
- * @return the result of the replace operation
+ * @return The result of the replace operation
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
*/
@@ -1048,7 +1056,7 @@
* the start position of the variable including the prefix, valid
* @param endPos
* the end position of the variable including the suffix, valid
- * @return the variable's value or <b>null</b> if the variable is unknown
+ * @return The variable's value or <b>null</b> if the variable is unknown
*/
protected String resolveVariable(final String variableName, final TextStringBuilder buf, final int startPos,
final int endPos) {
@@ -1323,7 +1331,7 @@
* the length within the builder to be processed, must be valid
* @param priorVariables
* the stack keeping track of the replaced variables, may be null
- * @return the length change that occurs, unless priorVariables is null when the int represents a boolean flag as to
+ * @return The length change that occurs, unless priorVariables is null when the int represents a boolean flag as to
* whether any change occurred.
* @throws IllegalArgumentException
* if variable is not found when its allowed to throw exception
diff --git a/src/main/java/org/apache/commons/text/StringTokenizer.java b/src/main/java/org/apache/commons/text/StringTokenizer.java
index 395375a..5e9c1d6 100644
--- a/src/main/java/org/apache/commons/text/StringTokenizer.java
+++ b/src/main/java/org/apache/commons/text/StringTokenizer.java
@@ -425,7 +425,7 @@
/**
* Gets the number of tokens found in the String.
*
- * @return the number of matched tokens
+ * @return The number of matched tokens
*/
public int size() {
checkTokenized();
@@ -436,7 +436,7 @@
* Gets the next token from the String. Equivalent to {@link #next()} except it returns null rather than throwing
* {@link NoSuchElementException} when no tokens remain.
*
- * @return the next sequential token, or null when no more tokens are found
+ * @return The next sequential token, or null when no more tokens are found
*/
public String nextToken() {
if (hasNext()) {
@@ -448,7 +448,7 @@
/**
* Gets the previous token from the String.
*
- * @return the previous sequential token, or null when no more tokens are found
+ * @return The previous sequential token, or null when no more tokens are found
*/
public String previousToken() {
if (hasPrevious()) {
@@ -460,7 +460,7 @@
/**
* Gets a copy of the full token list as an independent modifiable array.
*
- * @return the tokens as a String array
+ * @return The tokens as a String array
*/
public String[] getTokenArray() {
checkTokenized();
@@ -470,7 +470,7 @@
/**
* Gets a copy of the full token list as an independent modifiable list.
*
- * @return the tokens as a String array
+ * @return The tokens as a String array
*/
public List<String> getTokenList() {
checkTokenized();
@@ -545,7 +545,7 @@
/**
* Gets the next token.
*
- * @return the next String token
+ * @return The next String token
* @throws NoSuchElementException
* if there are no more elements
*/
@@ -560,7 +560,7 @@
/**
* Gets the index of the next token to return.
*
- * @return the next token index
+ * @return The next token index
*/
@Override
public int nextIndex() {
@@ -581,7 +581,7 @@
/**
* Gets the token previous to the last returned token.
*
- * @return the previous token
+ * @return The previous token
*/
@Override
public String previous() {
@@ -594,7 +594,7 @@
/**
* Gets the index of the previous token.
*
- * @return the previous token index
+ * @return The previous token index
*/
@Override
public int previousIndex() {
@@ -675,7 +675,7 @@
* the start position within the character array, must be valid
* @param count
* the number of characters to tokenize, must be valid
- * @return the modifiable list of String tokens, unmodifiable if null array or zero count
+ * @return The modifiable list of String tokens, unmodifiable if null array or zero count
*/
protected List<String> tokenize(final char[] srcChars, final int offset, final int count) {
if (srcChars == null || count == 0) {
@@ -731,7 +731,7 @@
* a temporary work area
* @param tokenList
* the list of parsed tokens
- * @return the starting position of the next field (the character immediately after the delimiter), or -1 if end of
+ * @return The starting position of the next field (the character immediately after the delimiter), or -1 if end of
* string found
*/
private int readNextToken(final char[] srcChars, int start, final int len, final TextStringBuilder workArea,
@@ -786,7 +786,7 @@
* the start position of the matched quote, 0 if no quoting
* @param quoteLen
* the length of the matched quote, 0 if no quoting
- * @return the starting position of the next field (the character immediately after the delimiter, or if end of
+ * @return The starting position of the next field (the character immediately after the delimiter, or if end of
* string found, then the length of string
*/
private int readWithQuotes(final char[] srcChars, final int start, final int len, final TextStringBuilder workArea,
@@ -904,7 +904,7 @@
/**
* Gets the field delimiter matcher.
*
- * @return the delimiter matcher in use
+ * @return The delimiter matcher in use
*/
public StringMatcher getDelimiterMatcher() {
return this.delimMatcher;
@@ -958,7 +958,7 @@
* The quote character is used to wrap data between the tokens. This enables delimiters to be entered as data. The
* default value is '"' (double quote).
*
- * @return the quote matcher in use
+ * @return The quote matcher in use
*/
public StringMatcher getQuoteMatcher() {
return quoteMatcher;
@@ -1001,7 +1001,7 @@
* These characters are ignored when parsing the String, unless they are within a quoted region. The default value
* is not to ignore anything.
*
- * @return the ignored matcher in use
+ * @return The ignored matcher in use
*/
public StringMatcher getIgnoredMatcher() {
return ignoredMatcher;
@@ -1044,7 +1044,7 @@
* These characters are trimmed off on each side of the delimiter until the token or quote is found. The default
* value is not to trim anything.
*
- * @return the trimmer matcher in use
+ * @return The trimmer matcher in use
*/
public StringMatcher getTrimmerMatcher() {
return trimmerMatcher;
@@ -1114,7 +1114,7 @@
/**
* Gets the String content that the tokenizer is parsing.
*
- * @return the string content being parsed
+ * @return The string content being parsed
*/
public String getContent() {
if (chars == null) {
@@ -1161,7 +1161,7 @@
/**
* Gets the String content that the tokenizer is parsing.
*
- * @return the string content being parsed
+ * @return The string content being parsed
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/text/TextStringBuilder.java b/src/main/java/org/apache/commons/text/TextStringBuilder.java
index c2a431e..5aa461a 100644
--- a/src/main/java/org/apache/commons/text/TextStringBuilder.java
+++ b/src/main/java/org/apache/commons/text/TextStringBuilder.java
@@ -145,7 +145,7 @@
/**
* Gets the text to be appended when a new line is added.
*
- * @return the new line text, null means use system default
+ * @return The new line text, null means use system default
*/
public String getNewLineText() {
return newLine;
@@ -167,7 +167,7 @@
/**
* Gets the text to be appended when null is added.
*
- * @return the null text, null means no append
+ * @return The null text, null means no append
*/
public String getNullText() {
return nullText;
@@ -192,7 +192,7 @@
/**
* Gets the length of the string builder.
*
- * @return the length
+ * @return The length
*/
@Override
public int length() {
@@ -230,7 +230,7 @@
/**
* Gets the current size of the internal character array buffer.
*
- * @return the capacity
+ * @return The capacity
*/
public int capacity() {
return buffer.length;
@@ -272,7 +272,7 @@
* <p>
* This method is the same as {@link #length()} and is provided to match the API of Collections.
*
- * @return the length
+ * @return The length
*/
public int size() {
return size;
@@ -313,7 +313,7 @@
* @see #deleteCharAt(int)
* @param index
* the index to retrieve, must be valid
- * @return the character at the index
+ * @return The character at the index
* @throws IndexOutOfBoundsException
* if the index is invalid
*/
@@ -407,7 +407,7 @@
*
* @param destination
* the destination array, null will cause an array to be created
- * @return the input array, unless that was null or too small
+ * @return The input array, unless that was null or too small
*/
public char[] getChars(char[] destination) {
final int len = length();
@@ -455,7 +455,7 @@
*
* @param readable
* object to read from
- * @return the number of characters read
+ * @return The number of characters read
* @throws IOException
* if an I/O error occurs
*
@@ -2383,7 +2383,7 @@
*
* @param start
* the start index, inclusive, must be valid
- * @return the new string
+ * @return The new string
* @throws IndexOutOfBoundsException
* if the index is invalid
*/
@@ -2401,7 +2401,7 @@
* 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
+ * @return The new string
* @throws IndexOutOfBoundsException
* if the index is invalid
*/
@@ -2418,7 +2418,7 @@
*
* @param length
* the number of characters to extract, negative returns empty string
- * @return the new string
+ * @return The new string
*/
public String leftString(final int length) {
if (length <= 0) {
@@ -2438,7 +2438,7 @@
*
* @param length
* the number of characters to extract, negative returns empty string
- * @return the new string
+ * @return The new string
*/
public String rightString(final int length) {
if (length <= 0) {
@@ -2462,7 +2462,7 @@
* the index to start at, negative means zero
* @param length
* the number of characters to extract, negative returns empty string
- * @return the new string
+ * @return The new string
*/
public String midString(int index, final int length) {
if (index < 0) {
@@ -2526,7 +2526,7 @@
*
* @param ch
* the character to find
- * @return the first index of the character, or -1 if not found
+ * @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch) {
return indexOf(ch, 0);
@@ -2539,7 +2539,7 @@
* 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
+ * @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2562,7 +2562,7 @@
*
* @param str
* the string to find, null returns -1
- * @return the first index of the string, or -1 if not found
+ * @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str) {
return indexOf(str, 0);
@@ -2578,7 +2578,7 @@
* 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
+ * @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2616,7 +2616,7 @@
*
* @param matcher
* the matcher to use, null returns -1
- * @return the first index matched, or -1 if not found
+ * @return The first index matched, or -1 if not found
*/
public int indexOf(final StringMatcher matcher) {
return indexOf(matcher, 0);
@@ -2632,7 +2632,7 @@
* 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
+ * @return The first index matched, or -1 if not found
*/
public int indexOf(final StringMatcher matcher, int startIndex) {
startIndex = startIndex < 0 ? 0 : startIndex;
@@ -2655,7 +2655,7 @@
*
* @param ch
* the character to find
- * @return the last index of the character, or -1 if not found
+ * @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch) {
return lastIndexOf(ch, size - 1);
@@ -2668,7 +2668,7 @@
* 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
+ * @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2690,7 +2690,7 @@
*
* @param str
* the string to find, null returns -1
- * @return the last index of the string, or -1 if not found
+ * @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str) {
return lastIndexOf(str, size - 1);
@@ -2706,7 +2706,7 @@
* 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
+ * @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2742,7 +2742,7 @@
*
* @param matcher
* the matcher to use, null returns -1
- * @return the last index matched, or -1 if not found
+ * @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StringMatcher matcher) {
return lastIndexOf(matcher, size);
@@ -2758,7 +2758,7 @@
* 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
+ * @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StringMatcher matcher, int startIndex) {
startIndex = startIndex >= size ? size - 1 : startIndex;
@@ -2965,7 +2965,7 @@
* <p>
* Note that unlike StringBuffer, the string version returned is independent of the string builder.
*
- * @return the builder as a String
+ * @return The builder as a String
*/
@Override
public String toString() {
@@ -2975,7 +2975,7 @@
/**
* Gets a StringBuffer version of the string builder, creating a new instance each time the method is called.
*
- * @return the builder as a StringBuffer
+ * @return The builder as a StringBuffer
*/
public StringBuffer toStringBuffer() {
return new StringBuffer(size).append(buffer, 0, size);
@@ -2984,7 +2984,7 @@
/**
* Gets a StringBuilder version of the string builder, creating a new instance each time the method is called.
*
- * @return the builder as a StringBuilder
+ * @return The builder as a StringBuilder
*/
public StringBuilder toStringBuilder() {
return new StringBuilder(size).append(buffer, 0, size);
@@ -2993,7 +2993,7 @@
/**
* Implement the {@link Builder} interface.
*
- * @return the builder as a String
+ * @return The builder as a String
* @see #toString()
*/
@Override
@@ -3009,7 +3009,7 @@
* 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
+ * @return The new string
* @throws IndexOutOfBoundsException
* if the index is invalid
*/
diff --git a/src/main/java/org/apache/commons/text/WordUtils.java b/src/main/java/org/apache/commons/text/WordUtils.java
index a41ac41..682adc9 100644
--- a/src/main/java/org/apache/commons/text/WordUtils.java
+++ b/src/main/java/org/apache/commons/text/WordUtils.java
@@ -624,7 +624,7 @@
* </pre>
*
* @param str the String to swap case, may be null
- * @return the changed String, <code>null</code> if null String input
+ * @return The changed String, <code>null</code> if null String input
*/
public static String swapCase(final String str) {
if (StringUtils.isEmpty(str)) {
@@ -835,7 +835,7 @@
* @param appendToEnd String to be appended to the end of the abbreviated string.
* This is appended ONLY if the string was indeed abbreviated.
* The append does not count towards the lower or upper limits.
- * @return the abbreviated String.
+ * @return The abbreviated String.
*
* <pre>
* WordUtils.abbreviate("Now is the time for all good men", 0, 40, null)); = "Now"
diff --git a/src/main/java/org/apache/commons/text/diff/EditCommand.java b/src/main/java/org/apache/commons/text/diff/EditCommand.java
index 7920206..1abd71f 100644
--- a/src/main/java/org/apache/commons/text/diff/EditCommand.java
+++ b/src/main/java/org/apache/commons/text/diff/EditCommand.java
@@ -69,7 +69,7 @@
/**
* Returns the object associated with this command.
*
- * @return the object on which the command is applied
+ * @return The object on which the command is applied
*/
protected T getObject() {
return object;
diff --git a/src/main/java/org/apache/commons/text/diff/StringsComparator.java b/src/main/java/org/apache/commons/text/diff/StringsComparator.java
index 66ce4b0..fe96068 100644
--- a/src/main/java/org/apache/commons/text/diff/StringsComparator.java
+++ b/src/main/java/org/apache/commons/text/diff/StringsComparator.java
@@ -105,7 +105,7 @@
* sequence and the <code>equals</code> method is specialized.
* </p>
*
- * @return the edit script resulting from the comparison of the two
+ * @return The edit script resulting from the comparison of the two
* sequences
*/
public EditScript<Character> getScript() {
@@ -178,7 +178,7 @@
* @param end1 the end of the first sequence to be compared
* @param start2 the begin of the second sequence to be compared
* @param end2 the end of the second sequence to be compared
- * @return the middle snake
+ * @return The middle snake
*/
private Snake getMiddleSnake(final int start1, final int end1, final int start2, final int end2) {
// Myers Algorithm
@@ -260,7 +260,7 @@
* @param diag the value of the diagonal of the snake
* @param end1 the value of the end of the first sequence to be compared
* @param end2 the value of the end of the second sequence to be compared
- * @return the snake built
+ * @return The snake built
*/
private Snake buildSnake(final int start, final int diag, final int end1, final int end2) {
int end = start;
diff --git a/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java b/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java
index 515d841..b67d867 100644
--- a/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java
@@ -25,14 +25,23 @@
/**
* Decodes Base64 Strings.
* <p>
- * For example: {@code "SGVsbG9Xb3JsZCE="} -> {@code "HelloWorld!"}.
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
* </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
+ * </pre>
* <p>
* Using a {@link StringSubstitutor}:
* </p>
+ *
* <pre>
- * StringSubstitutor.createInterpolator().replace("${base64Decoder:SGVsbG9Xb3JsZCE=}"));
+ * StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
* </pre>
+ * <p>
+ * The above examples convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
+ * </p>
+ *
* @since 1.5
*/
final class Base64DecoderStringLookup extends AbstractStringLookup {
diff --git a/src/main/java/org/apache/commons/text/lookup/Base64EncoderStringLookup.java b/src/main/java/org/apache/commons/text/lookup/Base64EncoderStringLookup.java
index 5de9c04..8fd8bdb 100644
--- a/src/main/java/org/apache/commons/text/lookup/Base64EncoderStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/Base64EncoderStringLookup.java
@@ -20,9 +20,28 @@
import java.nio.charset.StandardCharsets;
import java.util.Base64;
+import org.apache.commons.text.StringSubstitutor;
+
/**
* Encodes Base64 Strings.
- *
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "HelloWorld!"} to {@code "SGVsbG9Xb3JsZCE="}.
+ * </p>
+ *
* @since 1.6
*/
final class Base64EncoderStringLookup extends AbstractStringLookup {
diff --git a/src/main/java/org/apache/commons/text/lookup/ConstantStringLookup.java b/src/main/java/org/apache/commons/text/lookup/ConstantStringLookup.java
index f4f8dca..a432d47 100644
--- a/src/main/java/org/apache/commons/text/lookup/ConstantStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/ConstantStringLookup.java
@@ -21,14 +21,15 @@
import java.util.concurrent.ConcurrentHashMap;
import org.apache.commons.lang3.ClassUtils;
+import org.apache.commons.text.StringSubstitutor;
/**
* <p>
- * A specialized lookup implementation that allows access to constant fields of classes.
+ * Looks up the value of a fully-qualified static final value.
* </p>
* <p>
* Sometimes it is necessary in a configuration file to refer to a constant defined in a class. This can be done with
- * this lookup implementation. Variable names passed in must be of the form {@code apackage.AClass.AFIELD}. The
+ * this lookup implementation. Variable names must be in the format {@code apackage.AClass.AFIELD}. The
* {@code lookup(String)} method will split the passed in string at the last dot, separating the fully qualified class
* name and the name of the constant (i.e. <b>static final</b>) member field. Then the class is loaded and the field's
* value is obtained using reflection.
@@ -38,6 +39,23 @@
* global) lookup object and serve multiple clients concurrently.
* </p>
* <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code java.awt.event.KeyEvent.VK_ESCAPE} to {@code "27"}.
+ * </p>
+ * <p>
* This class was adapted from Apache Commons Configuration.
* </p>
*
@@ -69,9 +87,8 @@
* cache. Otherwise this method will invoke the {@code resolveField()} method and pass in the name of the class and
* the field.
*
- * @param key
- * the name of the variable to be resolved
- * @return the value of this variable or <b>null</b> if it cannot be resolved
+ * @param key the name of the variable to be resolved
+ * @return The value of this variable or <b>null</b> if it cannot be resolved
*/
@Override
public synchronized String lookup(final String key) {
@@ -106,13 +123,10 @@
* {@code fetchClass()} to obtain the {@code java.lang.Class} object for the target class. Then it will use
* reflection to obtain the field's value. For this to work the field must be accessable.
*
- * @param className
- * the name of the class
- * @param fieldName
- * the name of the member field of that class to read
- * @return the field's value
- * @throws Exception
- * if an error occurs
+ * @param className the name of the class
+ * @param fieldName the name of the member field of that class to read
+ * @return The field's value
+ * @throws Exception if an error occurs
*/
protected Object resolveField(final String className, final String fieldName) throws Exception {
final Class<?> clazz = fetchClass(className);
@@ -128,11 +142,9 @@
* <code><a href="https://commons.apache.org/lang/api-release/org/apache/commons/lang/ClassUtils.html">
* ClassUtils</a></code>.
*
- * @param className
- * the name of the class to be loaded
- * @return the corresponding class object
- * @throws ClassNotFoundException
- * if the class cannot be loaded
+ * @param className the name of the class to be loaded
+ * @return The corresponding class object
+ * @throws ClassNotFoundException if the class cannot be loaded
*/
protected Class<?> fetchClass(final String className) throws ClassNotFoundException {
return ClassUtils.getClass(className);
diff --git a/src/main/java/org/apache/commons/text/lookup/DateStringLookup.java b/src/main/java/org/apache/commons/text/lookup/DateStringLookup.java
index e7f0114..5333b0e 100644
--- a/src/main/java/org/apache/commons/text/lookup/DateStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/DateStringLookup.java
@@ -21,10 +21,28 @@
import java.util.Date;
import org.apache.commons.lang3.time.FastDateFormat;
+import org.apache.commons.text.StringSubstitutor;
/**
* Formats the current date with the format given in the key in a format compatible with
* {@link java.text.SimpleDateFormat}.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "yyyy-MM-dd"} to todays's date, for example, {@code "2019-08-04"}.
+ * </p>
*/
final class DateStringLookup extends AbstractStringLookup {
@@ -43,11 +61,9 @@
/**
* Formats the given {@code date} long with the given {@code format}.
*
- * @param date
- * the date to format
- * @param format
- * the format string for {@link SimpleDateFormat}.
- * @return the formatted date
+ * @param date the date to format
+ * @param format the format string for {@link SimpleDateFormat}.
+ * @return The formatted date
*/
private String formatDate(final long date, final String format) {
FastDateFormat dateFormat = null;
@@ -68,8 +84,7 @@
* Formats the current date with the format given in the key in a format compatible with
* {@link java.text.SimpleDateFormat}.
*
- * @param key
- * the format to use. If null, the default {@link DateFormat} will be used.
+ * @param key the format to use. If null, the default {@link DateFormat} will be used.
* @return The value of the environment variable.
*/
@Override
diff --git a/src/main/java/org/apache/commons/text/lookup/EnvironmentVariableStringLookup.java b/src/main/java/org/apache/commons/text/lookup/EnvironmentVariableStringLookup.java
index e6e5d49..398629a 100644
--- a/src/main/java/org/apache/commons/text/lookup/EnvironmentVariableStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/EnvironmentVariableStringLookup.java
@@ -16,9 +16,29 @@
*/
package org.apache.commons.text.lookup;
+import org.apache.commons.text.StringSubstitutor;
+
/**
* Looks up keys from environment variables.
- *
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.dateStringLookup().lookup("USER");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert (on Linux) {@code "USER"} to the current user name. On Windows 10, you would use
+ * {@code "USERNAME"} to the same effect.
+ * </p>
+ *
* @since 1.3
*/
final class EnvironmentVariableStringLookup extends AbstractStringLookup {
@@ -38,8 +58,7 @@
/**
* Looks up the value of the given environment variable.
*
- * @param key
- * the key to be looked up, may be null
+ * @param key the key to be looked up, may be null
* @return The value of the environment variable.
* @see System#getenv(String)
*/
diff --git a/src/main/java/org/apache/commons/text/lookup/FileStringLookup.java b/src/main/java/org/apache/commons/text/lookup/FileStringLookup.java
index 66863a1..503d308 100644
--- a/src/main/java/org/apache/commons/text/lookup/FileStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/FileStringLookup.java
@@ -20,13 +20,26 @@
import java.nio.file.Files;
import java.nio.file.Paths;
+import org.apache.commons.text.StringSubstitutor;
+
/**
* Looks up keys from an XML document.
* <p>
- * Looks up the value for a given key in the format "Charset:Path".
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
* </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.fileStringLookup().lookup(UTF-8:com/domain/document.properties");
+ * </pre>
* <p>
- * For example: "UTF-8:com/domain/document.properties".
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.properties} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "UTF-8:SomePath"} to the contents of the file.
* </p>
*
* @since 1.5
@@ -51,8 +64,7 @@
* For example: "com/domain/document.xml:/path/to/node".
* </p>
*
- * @param key
- * the key to be looked up, may be null
+ * @param key the key to be looked up, may be null
* @return The value associated with the key.
*/
@Override
diff --git a/src/main/java/org/apache/commons/text/lookup/InterpolatorStringLookup.java b/src/main/java/org/apache/commons/text/lookup/InterpolatorStringLookup.java
index 8476ec2..ce6d63c 100644
--- a/src/main/java/org/apache/commons/text/lookup/InterpolatorStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/InterpolatorStringLookup.java
@@ -106,7 +106,7 @@
/**
* Gets the lookup map.
*
- * @return the lookup map.
+ * @return The lookup map.
*/
public Map<String, StringLookup> getStringLookupMap() {
return stringLookupMap;
@@ -120,7 +120,7 @@
*
* @param var
* the name of the variable whose value is to be looked up
- * @return the value of this variable or <b>null</b> if it cannot be resolved
+ * @return The value of this variable or <b>null</b> if it cannot be resolved
*/
@Override
public String lookup(String var) {
diff --git a/src/main/java/org/apache/commons/text/lookup/JavaPlatformStringLookup.java b/src/main/java/org/apache/commons/text/lookup/JavaPlatformStringLookup.java
index 8afe71a..fff9b79 100644
--- a/src/main/java/org/apache/commons/text/lookup/JavaPlatformStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/JavaPlatformStringLookup.java
@@ -137,7 +137,7 @@
* the prefix to use for the result string
* @param name
* a system property name.
- * @return the prefix + a system property value.
+ * @return The prefix + a system property value.
*/
private String getSystemProperty(final String prefix, final String name) {
final String value = getSystemProperty(name);
diff --git a/src/main/java/org/apache/commons/text/lookup/MapStringLookup.java b/src/main/java/org/apache/commons/text/lookup/MapStringLookup.java
index ecb57c6..9a74de3 100644
--- a/src/main/java/org/apache/commons/text/lookup/MapStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/MapStringLookup.java
@@ -59,7 +59,7 @@
/**
* Gets the map used in lookups.
*
- * @return the map used in lookups.
+ * @return The map used in lookups.
*/
Map<String, V> getMap() {
return map;
@@ -73,7 +73,7 @@
*
* @param key
* the key to be looked up, may be null.
- * @return the matching value, null if no match
+ * @return The matching value, null if no match
*/
@Override
public String lookup(final String key) {
diff --git a/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java b/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java
index f471c84..701d013 100644
--- a/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java
@@ -30,7 +30,7 @@
* Looks up the value for a given key in the format "Document:Key".
* </p>
* <p>
- * For example: {@code "javascript:\"Hello World!\""}.
+ * For example: {@code "javascript:3 + 4"}.
* </p>
* <p>
* Using a {@link StringSubstitutor}:
diff --git a/src/main/java/org/apache/commons/text/lookup/StringLookup.java b/src/main/java/org/apache/commons/text/lookup/StringLookup.java
index 93e7e80..3201c5e 100644
--- a/src/main/java/org/apache/commons/text/lookup/StringLookup.java
+++ b/src/main/java/org/apache/commons/text/lookup/StringLookup.java
@@ -56,7 +56,7 @@
*
* @param key
* the key to look up, may be null
- * @return the matching value, null if no match
+ * @return The matching value, null if no match
*/
String lookup(String key);
}
diff --git a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
index 8fbf9b4..7cfc90b 100644
--- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
+++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
@@ -19,6 +19,8 @@
import java.util.Map;
+import org.apache.commons.text.StringSubstitutor;
+
/**
* Provides access to lookups defined in this package.
* <p>
@@ -283,8 +285,7 @@
/**
* Adds the {@link StringLookupFactory default lookups}.
*
- * @param stringLookupMap
- * the map of string lookups.
+ * @param stringLookupMap the map of string lookups.
* @since 1.5
*/
public void addDefaultStringLookups(final Map<String, StringLookup> stringLookupMap) {
@@ -298,10 +299,26 @@
}
/**
- * Returns the Base64DecoderStringLookup singleton instance to format the current date with the format given in the
- * key in a format compatible with {@link java.text.SimpleDateFormat}.
- *
- * @return the DateStringLookup singleton instance.
+ * Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
+ * </p>
+ *
+ * @return The DateStringLookup singleton instance.
* @since 1.5
*/
public StringLookup base64DecoderStringLookup() {
@@ -309,10 +326,26 @@
}
/**
- * Returns the Base64EncoderStringLookup singleton instance to format the current date with the format given in the
- * key in a format compatible with {@link java.text.SimpleDateFormat}.
- *
- * @return the DateStringLookup singleton instance.
+ * Returns the Base64EncoderStringLookup singleton instance to encode strings to Base64.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code } to {@code "SGVsbG9Xb3JsZCE="}.
+ * </p>
+ *
+ * @return The DateStringLookup singleton instance.
* @since 1.6
*/
public StringLookup base64EncoderStringLookup() {
@@ -320,10 +353,26 @@
}
/**
- * Returns the Base64DecoderStringLookup singleton instance to format the current date with the format given in the
- * key in a format compatible with {@link java.text.SimpleDateFormat}.
+ * Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
+ * </p>
*
- * @return the DateStringLookup singleton instance.
+ * @return The DateStringLookup singleton instance.
* @since 1.5
* @deprecated Use {@link #base64DecoderStringLookup()}.
*/
@@ -333,9 +382,37 @@
}
/**
- * Returns the ConstantStringLookup singleton instance to get the value of a fully-qualified static final value.
- *
- * @return the DateStringLookup singleton instance.
+ * Returns the ConstantStringLookup singleton instance to look up the value of a fully-qualified static final value.
+ * <p>
+ * Sometimes it is necessary in a configuration file to refer to a constant defined in a class. This can be done
+ * with this lookup implementation. Variable names must be in the format {@code apackage.AClass.AFIELD}. The
+ * {@code lookup(String)} method will split the passed in string at the last dot, separating the fully qualified
+ * class name and the name of the constant (i.e. <b>static final</b>) member field. Then the class is loaded and the
+ * field's value is obtained using reflection.
+ * </p>
+ * <p>
+ * Once retrieved values are cached for fast access. This class is thread-safe. It can be used as a standard (i.e.
+ * global) lookup object and serve multiple clients concurrently.
+ * </p>
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code java.awt.event.KeyEvent.VK_ESCAPE} to {@code "27"}.
+ * </p>
+ *
+ * @return The DateStringLookup singleton instance.
* @since 1.5
*/
public StringLookup constantStringLookup() {
@@ -345,8 +422,25 @@
/**
* Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a
* format compatible with {@link java.text.SimpleDateFormat}.
- *
- * @return the DateStringLookup singleton instance.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "yyyy-MM-dd"} to todays's date, for example, {@code "2019-08-04"}.
+ * </p>
+ *
+ * @return The DateStringLookup singleton instance.
*/
public StringLookup dateStringLookup() {
return DateStringLookup.INSTANCE;
@@ -355,8 +449,26 @@
/**
* Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable
* name.
- *
- * @return the EnvironmentVariableStringLookup singleton instance.
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.dateStringLookup().lookup("USER");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert (on Linux) {@code "USER"} to the current user name. On Windows 10, you would use
+ * {@code "USERNAME"} to the same effect.
+ * </p>
+ *
+ * @return The EnvironmentVariableStringLookup singleton instance.
*/
public StringLookup environmentVariableStringLookup() {
return EnvironmentVariableStringLookup.INSTANCE;
@@ -365,13 +477,24 @@
/**
* Returns the FileStringLookup singleton instance.
* <p>
- * Looks up the value for the key in the format "CharsetName:Path".
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
* </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");
+ * </pre>
* <p>
- * For example: "UTF-8:com/domain/document.properties".
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.properties} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "UTF-8:com/domain/document.properties"} to the contents of the file.
* </p>
*
- * @return the FileStringLookup singleton instance.
+ * @return The FileStringLookup singleton instance.
* @since 1.5
*/
public StringLookup fileStringLookup() {
@@ -380,6 +503,26 @@
/**
* Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
+ * <p>
+ * The lookups available to an interpolator are defined in
+ * </p>
+ * <p>
+ * Using a {@link StringLookup} from the {@link StringLookupFactory}:
+ * </p>
+ *
+ * <pre>
+ * StringLookupFactory.INSTANCE.interpolatorStringLookup().lookup("${sys:os.name}, ${env:USER}");
+ * </pre>
+ * <p>
+ * Using a {@link StringSubstitutor}:
+ * </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${sys:os.name}, ${env:USER} ..."));
+ * </pre>
+ * <p>
+ * The above examples convert {@code "${sys:os.name}, ${env:USER}"} to the OS name and Linux user name.
+ * </p>
*
* @return a new InterpolatorStringLookup.
*/
@@ -394,12 +537,9 @@
* {@code stringLookupMap}:
* </p>
*
- * @param stringLookupMap
- * the map of string lookups.
- * @param defaultStringLookup
- * the default string lookup.
- * @param addDefaultLookups
- * whether to use lookups as described above.
+ * @param stringLookupMap the map of string lookups.
+ * @param defaultStringLookup the default string lookup.
+ * @param addDefaultLookups whether to use lookups as described above.
* @return a new InterpolatorStringLookup.
* @since 1.4
*/
@@ -411,10 +551,8 @@
/**
* Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
*
- * @param <V>
- * the value type the default string lookup's map.
- * @param map
- * the default map for string lookups.
+ * @param <V> the value type the default string lookup's map.
+ * @param map the default map for string lookups.
* @return a new InterpolatorStringLookup.
*/
public <V> StringLookup interpolatorStringLookup(final Map<String, V> map) {
@@ -424,8 +562,7 @@
/**
* Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
*
- * @param defaultStringLookup
- * the default string lookup.
+ * @param defaultStringLookup the default string lookup.
* @return a new InterpolatorStringLookup.
*/
public StringLookup interpolatorStringLookup(final StringLookup defaultStringLookup) {
@@ -447,7 +584,7 @@
* <li><b>locale</b>: "default locale: en_US, platform encoding: iso-8859-1"</li>
* </ul>
*
- * @return the JavaPlatformStringLookup singleton instance.
+ * @return The JavaPlatformStringLookup singleton instance.
*/
public StringLookup javaPlatformStringLookup() {
return JavaPlatformStringLookup.INSTANCE;
@@ -461,7 +598,7 @@
* <li><b>address</b>: for the local host address, for example {@code 192.168.56.1}.</li>
* </ul>
*
- * @return the DateStringLookup singleton instance.
+ * @return The DateStringLookup singleton instance.
*/
public StringLookup localHostStringLookup() {
return LocalHostStringLookup.INSTANCE;
@@ -485,10 +622,8 @@
/**
* Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
*
- * @param <V>
- * the map value type.
- * @param map
- * the map.
+ * @param <V> the map value type.
+ * @param map the map.
* @return a new MapStringLookup.
*/
public <V> StringLookup mapStringLookup(final Map<String, V> map) {
@@ -498,7 +633,7 @@
/**
* Returns the NullStringLookup singleton instance which always returns null.
*
- * @return the NullStringLookup singleton instance.
+ * @return The NullStringLookup singleton instance.
*/
public StringLookup nullStringLookup() {
return NullStringLookup.INSTANCE;
@@ -513,7 +648,7 @@
* For example: "com/domain/document.properties:Key".
* </p>
*
- * @return the PropertiesStringLookup singleton instance.
+ * @return The PropertiesStringLookup singleton instance.
* @since 1.5
*/
public StringLookup propertiesStringLookup() {
@@ -529,7 +664,7 @@
* For example: "com.domain.messages:MyKey".
* </p>
*
- * @return the ResourceBundleStringLookup singleton instance.
+ * @return The ResourceBundleStringLookup singleton instance.
*/
public StringLookup resourceBundleStringLookup() {
return ResourceBundleStringLookup.INSTANCE;
@@ -544,8 +679,7 @@
* For example: "MyKey".
* </p>
*
- * @param bundleName
- * Only lookup in this bundle.
+ * @param bundleName Only lookup in this bundle.
* @return a ResourceBundleStringLookup instance for the given bundle name.
* @since 1.5
*/
@@ -562,7 +696,7 @@
* For example: "javascript:3+4".
* </p>
*
- * @return the ScriptStringLookup singleton instance.
+ * @return The ScriptStringLookup singleton instance.
* @since 1.5
*/
public StringLookup scriptStringLookup() {
@@ -572,7 +706,7 @@
/**
* Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.
*
- * @return the SystemPropertyStringLookup singleton instance.
+ * @return The SystemPropertyStringLookup singleton instance.
*/
public StringLookup systemPropertyStringLookup() {
return SystemPropertyStringLookup.INSTANCE;
@@ -587,7 +721,7 @@
* For example: "Hello%20World%21" becomes "Hello World!".
* </p>
*
- * @return the UrlStringLookup singleton instance.
+ * @return The UrlStringLookup singleton instance.
* @since 1.6
*/
public StringLookup urlDecoderStringLookup() {
@@ -603,7 +737,7 @@
* For example: "Hello World!" becomes "Hello+World%21".
* </p>
*
- * @return the UrlStringLookup singleton instance.
+ * @return The UrlStringLookup singleton instance.
* @since 1.6
*/
public StringLookup urlEncoderStringLookup() {
@@ -623,7 +757,7 @@
* "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties"
* </p>
*
- * @return the UrlStringLookup singleton instance.
+ * @return The UrlStringLookup singleton instance.
* @since 1.5
*/
public StringLookup urlStringLookup() {
@@ -639,7 +773,7 @@
* For example: "com/domain/document.xml:/path/to/node".
* </p>
*
- * @return the XmlStringLookup singleton instance.
+ * @return The XmlStringLookup singleton instance.
* @since 1.5
*/
public StringLookup xmlStringLookup() {
diff --git a/src/main/java/org/apache/commons/text/matcher/AbstractStringMatcher.java b/src/main/java/org/apache/commons/text/matcher/AbstractStringMatcher.java
index 34f9771..42bf02c 100644
--- a/src/main/java/org/apache/commons/text/matcher/AbstractStringMatcher.java
+++ b/src/main/java/org/apache/commons/text/matcher/AbstractStringMatcher.java
@@ -58,7 +58,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index of the active buffer, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -96,7 +96,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index of the active buffer, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -127,7 +127,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index of the active buffer, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -164,7 +164,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index of the active buffer, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
@Override
public int isMatch(final char[] buffer, int pos, final int bufferStart, final int bufferEnd) {
@@ -215,7 +215,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index of the active buffer, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
@Override
public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
@@ -247,7 +247,7 @@
* the text content to match against, do not change
* @param pos
* the starting position for the match, valid for buffer
- * @return the number of matching characters, zero for no match
+ * @return The number of matching characters, zero for no match
*/
public int isMatch(final char[] buffer, final int pos) {
return isMatch(buffer, pos, 0, buffer.length);
diff --git a/src/main/java/org/apache/commons/text/matcher/StringMatcher.java b/src/main/java/org/apache/commons/text/matcher/StringMatcher.java
index 4133955..01e90dc 100644
--- a/src/main/java/org/apache/commons/text/matcher/StringMatcher.java
+++ b/src/main/java/org/apache/commons/text/matcher/StringMatcher.java
@@ -48,7 +48,7 @@
* the first active index in the buffer, valid for buffer
* @param bufferEnd
* the end index (exclusive) of the active buffer, valid for buffer
- * @return the number of matching characters, or zero if there is no match
+ * @return The number of matching characters, or zero if there is no match
*/
int isMatch(char[] buffer, int pos, int bufferStart, int bufferEnd);
diff --git a/src/main/java/org/apache/commons/text/matcher/StringMatcherFactory.java b/src/main/java/org/apache/commons/text/matcher/StringMatcherFactory.java
index 988d150..81a9542 100644
--- a/src/main/java/org/apache/commons/text/matcher/StringMatcherFactory.java
+++ b/src/main/java/org/apache/commons/text/matcher/StringMatcherFactory.java
@@ -187,7 +187,7 @@
/**
* Matches the same characters as StringTokenizer, namely space, tab, newline and form feed.
*
- * @return the split matcher
+ * @return The split matcher
*/
public StringMatcher splitMatcher() {
return SPLIT_MATCHER;
@@ -219,7 +219,7 @@
/**
* Matches the String trim() whitespace characters.
*
- * @return the trim matcher
+ * @return The trim matcher
*/
public StringMatcher trimMatcher() {
return TRIM_MATCHER;
diff --git a/src/main/java/org/apache/commons/text/similarity/CosineSimilarity.java b/src/main/java/org/apache/commons/text/similarity/CosineSimilarity.java
index 39488ae..7405feb 100644
--- a/src/main/java/org/apache/commons/text/similarity/CosineSimilarity.java
+++ b/src/main/java/org/apache/commons/text/similarity/CosineSimilarity.java
@@ -88,7 +88,7 @@
* @param leftVector left vector
* @param rightVector right vector
* @param intersection common elements
- * @return the dot product
+ * @return The dot product
*/
private double dot(final Map<CharSequence, Integer> leftVector, final Map<CharSequence, Integer> rightVector,
final Set<CharSequence> intersection) {
diff --git a/src/main/java/org/apache/commons/text/similarity/EditDistance.java b/src/main/java/org/apache/commons/text/similarity/EditDistance.java
index cf4e2c0..5faf81f 100644
--- a/src/main/java/org/apache/commons/text/similarity/EditDistance.java
+++ b/src/main/java/org/apache/commons/text/similarity/EditDistance.java
@@ -51,7 +51,7 @@
*
* @param left the first CharSequence
* @param right the second CharSequence
- * @return the similarity score between two CharSequences
+ * @return The similarity score between two CharSequences
*/
@Override
R apply(CharSequence left, CharSequence right);
diff --git a/src/main/java/org/apache/commons/text/similarity/EditDistanceFrom.java b/src/main/java/org/apache/commons/text/similarity/EditDistanceFrom.java
index 691fef3..310b6bb 100644
--- a/src/main/java/org/apache/commons/text/similarity/EditDistanceFrom.java
+++ b/src/main/java/org/apache/commons/text/similarity/EditDistanceFrom.java
@@ -85,7 +85,7 @@
* </p>
*
* @param right the second CharSequence
- * @return the similarity score between two CharSequences
+ * @return The similarity score between two CharSequences
*/
public R apply(final CharSequence right) {
return editDistance.apply(left, right);
@@ -94,7 +94,7 @@
/**
* Gets the left parameter.
*
- * @return the left parameter
+ * @return The left parameter
*/
public CharSequence getLeft() {
return left;
@@ -103,7 +103,7 @@
/**
* Gets the edit distance.
*
- * @return the edit distance
+ * @return The edit distance
*/
public EditDistance<R> getEditDistance() {
return editDistance;
diff --git a/src/main/java/org/apache/commons/text/similarity/FuzzyScore.java b/src/main/java/org/apache/commons/text/similarity/FuzzyScore.java
index 48ea059..233a276 100644
--- a/src/main/java/org/apache/commons/text/similarity/FuzzyScore.java
+++ b/src/main/java/org/apache/commons/text/similarity/FuzzyScore.java
@@ -134,7 +134,7 @@
/**
* Gets the locale.
*
- * @return the locale
+ * @return The locale
*/
public Locale getLocale() {
return locale;
diff --git a/src/main/java/org/apache/commons/text/similarity/IntersectionSimilarity.java b/src/main/java/org/apache/commons/text/similarity/IntersectionSimilarity.java
index cd76065..d08bfbf 100644
--- a/src/main/java/org/apache/commons/text/similarity/IntersectionSimilarity.java
+++ b/src/main/java/org/apache/commons/text/similarity/IntersectionSimilarity.java
@@ -89,7 +89,7 @@
* looking up its count in the underlying map.
*
* @param object the object to search for
- * @return the number of occurrences of the object, zero if not found
+ * @return The number of occurrences of the object, zero if not found
*/
int getCount(final Object object) {
final BagCount count = map.get(object);
@@ -102,7 +102,7 @@
/**
* Returns a Set view of the mappings contained in this bag.
*
- * @return the Set view
+ * @return The Set view
*/
Set<Entry<T, BagCount>> entrySet() {
return map.entrySet();
@@ -111,7 +111,7 @@
/**
* Get the number of unique elements in the bag.
*
- * @return the unique element size
+ * @return The unique element size
*/
int uniqueElementSize() {
return map.size();
@@ -140,7 +140,7 @@
*
* @param left first character sequence
* @param right second character sequence
- * @return the intersection result
+ * @return The intersection result
* @throws IllegalArgumentException if either input sequence is {@code null}
*/
@Override
@@ -187,7 +187,7 @@
* in the collection.
*
* @param objects the objects
- * @return the bag
+ * @return The bag
*/
private TinyBag toBag(final Collection<T> objects) {
final TinyBag bag = new TinyBag(objects.size());
@@ -204,7 +204,7 @@
* @param <T> the type of the elements in the set
* @param setA the set A
* @param setB the set B
- * @return the intersection
+ * @return The intersection
*/
private static <T> int getIntersection(final Set<T> setA, final Set<T> setB) {
int intersection = 0;
@@ -222,7 +222,7 @@
*
* @param bagA the bag A
* @param bagB the bag B
- * @return the intersection
+ * @return The intersection
*/
private int getIntersection(final TinyBag bagA, final TinyBag bagB) {
int intersection = 0;
diff --git a/src/main/java/org/apache/commons/text/similarity/LevenshteinDetailedDistance.java b/src/main/java/org/apache/commons/text/similarity/LevenshteinDetailedDistance.java
index 6e92cb6..2560d22 100644
--- a/src/main/java/org/apache/commons/text/similarity/LevenshteinDetailedDistance.java
+++ b/src/main/java/org/apache/commons/text/similarity/LevenshteinDetailedDistance.java
@@ -109,7 +109,7 @@
/**
* Gets the default instance.
*
- * @return the default instace
+ * @return The default instace
*/
public static LevenshteinDetailedDistance getDefaultInstance() {
return DEFAULT_INSTANCE;
@@ -118,7 +118,7 @@
/**
* Gets the distance threshold.
*
- * @return the distance threshold
+ * @return The distance threshold
*/
public Integer getThreshold() {
return threshold;
diff --git a/src/main/java/org/apache/commons/text/similarity/LevenshteinDistance.java b/src/main/java/org/apache/commons/text/similarity/LevenshteinDistance.java
index d509a25..7814b4c 100644
--- a/src/main/java/org/apache/commons/text/similarity/LevenshteinDistance.java
+++ b/src/main/java/org/apache/commons/text/similarity/LevenshteinDistance.java
@@ -117,7 +117,7 @@
/**
* Gets the default instance.
*
- * @return the default instance
+ * @return The default instance
*/
public static LevenshteinDistance getDefaultInstance() {
return DEFAULT_INSTANCE;
@@ -126,7 +126,7 @@
/**
* Gets the distance threshold.
*
- * @return the distance threshold
+ * @return The distance threshold
*/
public Integer getThreshold() {
return threshold;
diff --git a/src/main/java/org/apache/commons/text/similarity/LongestCommonSubsequence.java b/src/main/java/org/apache/commons/text/similarity/LongestCommonSubsequence.java
index 78e9a46..a7de9bf 100644
--- a/src/main/java/org/apache/commons/text/similarity/LongestCommonSubsequence.java
+++ b/src/main/java/org/apache/commons/text/similarity/LongestCommonSubsequence.java
@@ -79,7 +79,7 @@
*
* @param left first character sequence
* @param right second character sequence
- * @return the longest common subsequence found
+ * @return The longest common subsequence found
* @throws IllegalArgumentException
* if either String input {@code null}
* @deprecated Deprecated as of 1.2 due to a typo in the method name.
@@ -110,7 +110,7 @@
*
* @param left first character sequence
* @param right second character sequence
- * @return the longest common subsequence found
+ * @return The longest common subsequence found
* @throws IllegalArgumentException
* if either String input {@code null}
* @since 1.2
diff --git a/src/main/java/org/apache/commons/text/similarity/SimilarityScore.java b/src/main/java/org/apache/commons/text/similarity/SimilarityScore.java
index e71fae9..f3723be 100644
--- a/src/main/java/org/apache/commons/text/similarity/SimilarityScore.java
+++ b/src/main/java/org/apache/commons/text/similarity/SimilarityScore.java
@@ -56,7 +56,7 @@
*
* @param left the first CharSequence
* @param right the second CharSequence
- * @return the similarity score between two CharSequences
+ * @return The similarity score between two CharSequences
*/
R apply(CharSequence left, CharSequence right);
diff --git a/src/main/java/org/apache/commons/text/similarity/SimilarityScoreFrom.java b/src/main/java/org/apache/commons/text/similarity/SimilarityScoreFrom.java
index 8d3e46e..22ffc41 100644
--- a/src/main/java/org/apache/commons/text/similarity/SimilarityScoreFrom.java
+++ b/src/main/java/org/apache/commons/text/similarity/SimilarityScoreFrom.java
@@ -85,7 +85,7 @@
* </p>
*
* @param right the second CharSequence
- * @return the similarity score between two CharSequences
+ * @return The similarity score between two CharSequences
*/
public R apply(final CharSequence right) {
return similarityScore.apply(left, right);
@@ -94,7 +94,7 @@
/**
* Gets the left parameter.
*
- * @return the left parameter
+ * @return The left parameter
*/
public CharSequence getLeft() {
return left;
@@ -103,7 +103,7 @@
/**
* Gets the edit distance.
*
- * @return the edit distance
+ * @return The edit distance
*/
public SimilarityScore<R> getSimilarityScore() {
return similarityScore;
diff --git a/src/main/java/org/apache/commons/text/translate/JavaUnicodeEscaper.java b/src/main/java/org/apache/commons/text/translate/JavaUnicodeEscaper.java
index b4b3aac..e30d77d 100644
--- a/src/main/java/org/apache/commons/text/translate/JavaUnicodeEscaper.java
+++ b/src/main/java/org/apache/commons/text/translate/JavaUnicodeEscaper.java
@@ -30,7 +30,7 @@
*
* @param codepoint
* above which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static JavaUnicodeEscaper above(final int codepoint) {
return outsideOf(0, codepoint);
@@ -43,7 +43,7 @@
*
* @param codepoint
* below which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static JavaUnicodeEscaper below(final int codepoint) {
return outsideOf(codepoint, Integer.MAX_VALUE);
@@ -58,7 +58,7 @@
* above which to escape
* @param codepointHigh
* below which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static JavaUnicodeEscaper between(final int codepointLow, final int codepointHigh) {
return new JavaUnicodeEscaper(codepointLow, codepointHigh, true);
@@ -73,7 +73,7 @@
* below which to escape
* @param codepointHigh
* above which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static JavaUnicodeEscaper outsideOf(final int codepointLow, final int codepointHigh) {
return new JavaUnicodeEscaper(codepointLow, codepointHigh, false);
@@ -102,7 +102,7 @@
*
* @param codepoint
* a Unicode code point
- * @return the hex string for the given codepoint
+ * @return The hex string for the given codepoint
*/
@Override
protected String toUtf16Escape(final int codepoint) {
diff --git a/src/main/java/org/apache/commons/text/translate/NumericEntityEscaper.java b/src/main/java/org/apache/commons/text/translate/NumericEntityEscaper.java
index b402974..f9bc7e7 100644
--- a/src/main/java/org/apache/commons/text/translate/NumericEntityEscaper.java
+++ b/src/main/java/org/apache/commons/text/translate/NumericEntityEscaper.java
@@ -58,7 +58,7 @@
* <p>Constructs a <code>NumericEntityEscaper</code> below the specified value (exclusive). </p>
*
* @param codepoint below which to escape
- * @return the newly created {@code NumericEntityEscaper} instance
+ * @return The newly created {@code NumericEntityEscaper} instance
*/
public static NumericEntityEscaper below(final int codepoint) {
return outsideOf(codepoint, Integer.MAX_VALUE);
@@ -68,7 +68,7 @@
* <p>Constructs a <code>NumericEntityEscaper</code> above the specified value (exclusive). </p>
*
* @param codepoint above which to escape
- * @return the newly created {@code NumericEntityEscaper} instance
+ * @return The newly created {@code NumericEntityEscaper} instance
*/
public static NumericEntityEscaper above(final int codepoint) {
return outsideOf(0, codepoint);
@@ -79,7 +79,7 @@
*
* @param codepointLow above which to escape
* @param codepointHigh below which to escape
- * @return the newly created {@code NumericEntityEscaper} instance
+ * @return The newly created {@code NumericEntityEscaper} instance
*/
public static NumericEntityEscaper between(final int codepointLow, final int codepointHigh) {
return new NumericEntityEscaper(codepointLow, codepointHigh, true);
@@ -90,7 +90,7 @@
*
* @param codepointLow below which to escape
* @param codepointHigh above which to escape
- * @return the newly created {@code NumericEntityEscaper} instance
+ * @return The newly created {@code NumericEntityEscaper} instance
*/
public static NumericEntityEscaper outsideOf(final int codepointLow, final int codepointHigh) {
return new NumericEntityEscaper(codepointLow, codepointHigh, false);
diff --git a/src/main/java/org/apache/commons/text/translate/SinglePassTranslator.java b/src/main/java/org/apache/commons/text/translate/SinglePassTranslator.java
index 1375344..cfd12c9 100644
--- a/src/main/java/org/apache/commons/text/translate/SinglePassTranslator.java
+++ b/src/main/java/org/apache/commons/text/translate/SinglePassTranslator.java
@@ -40,7 +40,7 @@
/**
* A utility method to be used in the {@link #translate(CharSequence, int, Writer)} method.
*
- * @return the name of this or the extending class.
+ * @return The name of this or the extending class.
*/
private String getClassName() {
final Class<? extends SinglePassTranslator> clazz = this.getClass();
diff --git a/src/main/java/org/apache/commons/text/translate/UnicodeEscaper.java b/src/main/java/org/apache/commons/text/translate/UnicodeEscaper.java
index a78a719..34dde03 100644
--- a/src/main/java/org/apache/commons/text/translate/UnicodeEscaper.java
+++ b/src/main/java/org/apache/commons/text/translate/UnicodeEscaper.java
@@ -61,7 +61,7 @@
* <p>Constructs a <code>UnicodeEscaper</code> below the specified value (exclusive). </p>
*
* @param codepoint below which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static UnicodeEscaper below(final int codepoint) {
return outsideOf(codepoint, Integer.MAX_VALUE);
@@ -71,7 +71,7 @@
* <p>Constructs a <code>UnicodeEscaper</code> above the specified value (exclusive). </p>
*
* @param codepoint above which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static UnicodeEscaper above(final int codepoint) {
return outsideOf(0, codepoint);
@@ -82,7 +82,7 @@
*
* @param codepointLow below which to escape
* @param codepointHigh above which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static UnicodeEscaper outsideOf(final int codepointLow, final int codepointHigh) {
return new UnicodeEscaper(codepointLow, codepointHigh, false);
@@ -93,7 +93,7 @@
*
* @param codepointLow above which to escape
* @param codepointHigh below which to escape
- * @return the newly created {@code UnicodeEscaper} instance
+ * @return The newly created {@code UnicodeEscaper} instance
*/
public static UnicodeEscaper between(final int codepointLow, final int codepointHigh) {
return new UnicodeEscaper(codepointLow, codepointHigh, true);
@@ -131,7 +131,7 @@
*
* @param codepoint
* a Unicode code point
- * @return the hex string for the given codepoint
+ * @return The hex string for the given codepoint
*
*/
protected String toUtf16Escape(final int codepoint) {
diff --git a/src/test/java/org/apache/commons/text/lookup/DateStringLookupTest.java b/src/test/java/org/apache/commons/text/lookup/DateStringLookupTest.java
index 69df25e..2371942 100644
--- a/src/test/java/org/apache/commons/text/lookup/DateStringLookupTest.java
+++ b/src/test/java/org/apache/commons/text/lookup/DateStringLookupTest.java
@@ -43,6 +43,7 @@
public void testFormat() {
final String fomat = "yyyy-MM-dd";
final String value = DateStringLookup.INSTANCE.lookup(fomat);
+ // System.out.println(value);
assertNotNull(value, "No Date");
final SimpleDateFormat format = new SimpleDateFormat(fomat);
final String today = format.format(new Date());