You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2019/08/04 15:36:07 UTC
[commons-text] branch master updated (d81879e -> 42e7659)
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git.
from d81879e [TEXT-170] Add String lookup for host names and IP addresses (#118)
new d69181f Sort members.
new 45eb67d Sort members.
new 7576289 Expand Javadocs.
new 3ba2268 [TEXT-170] Add String lookup for host names and IP addresses (#118)
new 42e7659 Expand Javadoc for StringSubstitutor and friends.
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
pom.xml | 2 +-
src/changes/changes.xml | 2 +
.../org/apache/commons/text/AlphabetConverter.java | 14 +-
src/main/java/org/apache/commons/text/Builder.java | 2 +-
.../org/apache/commons/text/CompositeFormat.java | 2 +-
.../org/apache/commons/text/FormattableUtils.java | 10 +-
.../apache/commons/text/RandomStringGenerator.java | 10 +-
.../java/org/apache/commons/text/StrBuilder.java | 60 +++---
.../java/org/apache/commons/text/StrLookup.java | 2 +-
.../java/org/apache/commons/text/StrMatcher.java | 18 +-
.../org/apache/commons/text/StrSubstitutor.java | 50 ++---
.../java/org/apache/commons/text/StrTokenizer.java | 36 ++--
.../org/apache/commons/text/StringEscapeUtils.java | 6 +-
.../org/apache/commons/text/StringSubstitutor.java | 60 +++---
.../org/apache/commons/text/StringTokenizer.java | 36 ++--
.../org/apache/commons/text/TextStringBuilder.java | 60 +++---
.../java/org/apache/commons/text/WordUtils.java | 4 +-
.../org/apache/commons/text/diff/EditCommand.java | 2 +-
.../commons/text/diff/StringsComparator.java | 6 +-
.../text/lookup/Base64DecoderStringLookup.java | 13 +-
.../text/lookup/Base64EncoderStringLookup.java | 21 +-
.../commons/text/lookup/ConstantStringLookup.java | 46 ++--
.../commons/text/lookup/DateStringLookup.java | 29 ++-
.../lookup/EnvironmentVariableStringLookup.java | 25 ++-
.../commons/text/lookup/FileStringLookup.java | 20 +-
.../text/lookup/InterpolatorStringLookup.java | 4 +-
.../text/lookup/JavaPlatformStringLookup.java | 2 +-
.../commons/text/lookup/MapStringLookup.java | 4 +-
.../commons/text/lookup/ScriptStringLookup.java | 2 +-
.../apache/commons/text/lookup/StringLookup.java | 2 +-
.../commons/text/lookup/StringLookupFactory.java | 238 ++++++++++++++++-----
.../text/matcher/AbstractStringMatcher.java | 12 +-
.../apache/commons/text/matcher/StringMatcher.java | 2 +-
.../commons/text/matcher/StringMatcherFactory.java | 4 +-
.../commons/text/similarity/CosineSimilarity.java | 2 +-
.../commons/text/similarity/EditDistance.java | 2 +-
.../commons/text/similarity/EditDistanceFrom.java | 6 +-
.../apache/commons/text/similarity/FuzzyScore.java | 2 +-
.../text/similarity/IntersectionSimilarity.java | 14 +-
.../similarity/LevenshteinDetailedDistance.java | 4 +-
.../text/similarity/LevenshteinDistance.java | 4 +-
.../text/similarity/LongestCommonSubsequence.java | 4 +-
.../commons/text/similarity/SimilarityScore.java | 2 +-
.../text/similarity/SimilarityScoreFrom.java | 6 +-
.../commons/text/translate/JavaUnicodeEscaper.java | 10 +-
.../text/translate/NumericEntityEscaper.java | 8 +-
.../text/translate/SinglePassTranslator.java | 2 +-
.../commons/text/translate/UnicodeEscaper.java | 10 +-
.../commons/text/lookup/DateStringLookupTest.java | 1 +
49 files changed, 557 insertions(+), 326 deletions(-)
[commons-text] 03/05: Expand Javadocs.
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit 75762892caff4c06f72c7c41d379dd803313bc8e
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 4 11:30:25 2019 -0400
Expand Javadocs.
---
pom.xml | 2 +-
.../org/apache/commons/text/AlphabetConverter.java | 14 +-
src/main/java/org/apache/commons/text/Builder.java | 2 +-
.../org/apache/commons/text/CompositeFormat.java | 2 +-
.../org/apache/commons/text/FormattableUtils.java | 10 +-
.../apache/commons/text/RandomStringGenerator.java | 10 +-
.../java/org/apache/commons/text/StrBuilder.java | 60 +++---
.../java/org/apache/commons/text/StrLookup.java | 2 +-
.../java/org/apache/commons/text/StrMatcher.java | 18 +-
.../org/apache/commons/text/StrSubstitutor.java | 50 ++---
.../java/org/apache/commons/text/StrTokenizer.java | 36 ++--
.../org/apache/commons/text/StringEscapeUtils.java | 6 +-
.../org/apache/commons/text/StringSubstitutor.java | 55 ++---
.../org/apache/commons/text/StringTokenizer.java | 36 ++--
.../org/apache/commons/text/TextStringBuilder.java | 60 +++---
.../java/org/apache/commons/text/WordUtils.java | 4 +-
.../org/apache/commons/text/diff/EditCommand.java | 2 +-
.../commons/text/diff/StringsComparator.java | 6 +-
.../text/lookup/Base64DecoderStringLookup.java | 13 +-
.../text/lookup/Base64EncoderStringLookup.java | 21 +-
.../commons/text/lookup/ConstantStringLookup.java | 46 ++--
.../commons/text/lookup/DateStringLookup.java | 29 ++-
.../lookup/EnvironmentVariableStringLookup.java | 25 ++-
.../commons/text/lookup/FileStringLookup.java | 20 +-
.../text/lookup/InterpolatorStringLookup.java | 4 +-
.../text/lookup/JavaPlatformStringLookup.java | 2 +-
.../commons/text/lookup/MapStringLookup.java | 4 +-
.../commons/text/lookup/ScriptStringLookup.java | 2 +-
.../apache/commons/text/lookup/StringLookup.java | 2 +-
.../commons/text/lookup/StringLookupFactory.java | 238 ++++++++++++++++-----
.../text/matcher/AbstractStringMatcher.java | 12 +-
.../apache/commons/text/matcher/StringMatcher.java | 2 +-
.../commons/text/matcher/StringMatcherFactory.java | 4 +-
.../commons/text/similarity/CosineSimilarity.java | 2 +-
.../commons/text/similarity/EditDistance.java | 2 +-
.../commons/text/similarity/EditDistanceFrom.java | 6 +-
.../apache/commons/text/similarity/FuzzyScore.java | 2 +-
.../text/similarity/IntersectionSimilarity.java | 14 +-
.../similarity/LevenshteinDetailedDistance.java | 4 +-
.../text/similarity/LevenshteinDistance.java | 4 +-
.../text/similarity/LongestCommonSubsequence.java | 4 +-
.../commons/text/similarity/SimilarityScore.java | 2 +-
.../text/similarity/SimilarityScoreFrom.java | 6 +-
.../commons/text/translate/JavaUnicodeEscaper.java | 10 +-
.../text/translate/NumericEntityEscaper.java | 8 +-
.../text/translate/SinglePassTranslator.java | 2 +-
.../commons/text/translate/UnicodeEscaper.java | 10 +-
...ubstitutorWithInterpolatorStringLookupTest.java | 16 +-
.../commons/text/lookup/DateStringLookupTest.java | 1 +
49 files changed, 562 insertions(+), 330 deletions(-)
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 @@ public final class AlphabetConverter {
* 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 @@ public final class AlphabetConverter {
*
* @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 @@ public final class AlphabetConverter {
* 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 @@ public final class AlphabetConverter {
* 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 @@ public final class AlphabetConverter {
* 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 @@ public final class AlphabetConverter {
* @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 @@ public final class AlphabetConverter {
* @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 @@ public interface Builder<T> {
* 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 @@ public class CompositeFormat extends Format {
* @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 @@ public class FormattableUtils {
* {@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 @@ public class FormattableUtils {
* @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 @@ public class FormattableUtils {
* @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 @@ public class FormattableUtils {
* @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 @@ public class FormattableUtils {
* @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 @@ public final class RandomStringGenerator {
* 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 @@ public final class RandomStringGenerator {
* 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 @@ public final class RandomStringGenerator {
*
* @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 @@ public final class RandomStringGenerator {
* 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 @@ public final class RandomStringGenerator {
/**
* <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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
/**
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
/**
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
/**
* Gets the length of the string builder.
*
- * @return the length
+ * @return The length
*/
@Override
public int length() {
@@ -214,7 +214,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
/**
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
*
* @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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* 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 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
/**
* Implement the {@link Builder} interface.
- * @return the builder as a String
+ * @return The builder as a String
* @see #toString()
*/
@Override
@@ -2850,7 +2850,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* @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 @@ public abstract class StrLookup<V> implements StringLookup {
* 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 @@ public abstract class StrMatcher {
* 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 @@ public abstract class StrMatcher {
/**
* 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 @@ public abstract class StrMatcher {
* @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 @@ public abstract class StrMatcher {
*
* @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 @@ public abstract class StrMatcher {
* @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 @@ public abstract class StrMatcher {
* @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 @@ public abstract class StrMatcher {
* @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 @@ public abstract class StrMatcher {
* @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 @@ public abstract class StrMatcher {
* @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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
*
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
* @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 @@ public class StrSubstitutor {
/**
* 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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* <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 @@ public class StrSubstitutor {
/**
* 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 @@ public class StrSubstitutor {
/**
* 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 @@ public class StrSubstitutor {
* 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 @@ public class StrSubstitutor {
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* @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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* @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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* @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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringEscapeUtils {
/**
* <p>Return the escaped string.</p>
*
- * @return the escaped string
+ * @return The escaped string
*/
@Override
public String toString() {
@@ -801,7 +801,7 @@ public class StringEscapeUtils {
* <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 @@ public class StringEscapeUtils {
* <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 535cd78..99b9c7a 100644
--- a/src/main/java/org/apache/commons/text/StringSubstitutor.java
+++ b/src/main/java/org/apache/commons/text/StringSubstitutor.java
@@ -188,6 +188,9 @@ public class StringSubstitutor {
* 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.
@@ -207,7 +210,7 @@ public class StringSubstitutor {
* 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
*/
@@ -229,7 +232,7 @@ public class StringSubstitutor {
* 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
@@ -248,7 +251,7 @@ public class StringSubstitutor {
* 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
*/
@@ -272,7 +275,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -535,7 +538,7 @@ public class StringSubstitutor {
/**
* 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;
@@ -546,7 +549,7 @@ public class StringSubstitutor {
/**
* Gets the StringLookup that is used to lookup variables.
*
- * @return the StringLookup
+ * @return The StringLookup
*/
public StringLookup getStringLookup() {
return this.variableResolver;
@@ -563,7 +566,7 @@ public class StringSubstitutor {
* <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;
@@ -577,7 +580,7 @@ public class StringSubstitutor {
* 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;
@@ -591,7 +594,7 @@ public class StringSubstitutor {
* 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;
@@ -616,7 +619,7 @@ public class StringSubstitutor {
* Hi Douglas ${surname}
* </pre>
*
- * @return the substitution in variable values flag
+ * @return The substitution in variable values flag
*/
public boolean isDisableSubstitutionInValues() {
return disableSubstitutionInValues;
@@ -627,7 +630,7 @@ public class StringSubstitutor {
/**
* 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;
@@ -637,7 +640,7 @@ public class StringSubstitutor {
* 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;
@@ -646,7 +649,7 @@ public class StringSubstitutor {
/**
* 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;
@@ -659,7 +662,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -685,7 +688,7 @@ public class StringSubstitutor {
* 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
*/
@@ -704,7 +707,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -728,7 +731,7 @@ public class StringSubstitutor {
* 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
*/
@@ -748,7 +751,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -768,7 +771,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -796,7 +799,7 @@ public class StringSubstitutor {
* 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
*/
@@ -818,7 +821,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -844,7 +847,7 @@ public class StringSubstitutor {
* 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
*/
@@ -864,7 +867,7 @@ public class StringSubstitutor {
*
* @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
*/
@@ -890,7 +893,7 @@ public class StringSubstitutor {
* 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
*/
@@ -1053,7 +1056,7 @@ public class StringSubstitutor {
* 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) {
@@ -1328,7 +1331,7 @@ public class StringSubstitutor {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class StringTokenizer implements ListIterator<String>, Cloneable {
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* Gets the length of the string builder.
*
- * @return the length
+ * @return The length
*/
@Override
public int length() {
@@ -230,7 +230,7 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* <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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
*
* @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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* <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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* 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 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
/**
* Implement the {@link Builder} interface.
*
- * @return the builder as a String
+ * @return The builder as a String
* @see #toString()
*/
@Override
@@ -3009,7 +3009,7 @@ public class TextStringBuilder implements CharSequence, Appendable, Serializable
* 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 @@ public class WordUtils {
* </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 @@ public class WordUtils {
* @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 @@ public abstract class EditCommand<T> {
/**
* 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 @@ public class StringsComparator {
* 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 @@ public class StringsComparator {
* @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 @@ public class StringsComparator {
* @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 @@ import org.apache.commons.text.StringSubstitutor;
/**
* 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 @@ package org.apache.commons.text.lookup;
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.Objects;
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 @@ import org.apache.commons.lang3.ClassUtils;
* 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 @@ class ConstantStringLookup extends AbstractStringLookup {
* 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 @@ class ConstantStringLookup extends AbstractStringLookup {
* {@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 @@ class ConstantStringLookup extends AbstractStringLookup {
* <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.text.SimpleDateFormat;
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 @@ final class DateStringLookup extends AbstractStringLookup {
/**
* 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 @@ final class DateStringLookup extends AbstractStringLookup {
* 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 @@ final class EnvironmentVariableStringLookup extends AbstractStringLookup {
/**
* 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 @@ package org.apache.commons.text.lookup;
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>
+ * Using a {@link StringSubstitutor}:
* </p>
+ *
+ * <pre>
+ * StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.properties} ..."));
+ * </pre>
* <p>
- * For example: "UTF-8:com/domain/document.properties".
+ * The above examples convert {@code "UTF-8:SomePath"} to the contents of the file.
* </p>
*
* @since 1.5
@@ -51,8 +64,7 @@ final class FileStringLookup extends AbstractStringLookup {
* 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 @@ class InterpolatorStringLookup extends AbstractStringLookup {
/**
* Gets the lookup map.
*
- * @return the lookup map.
+ * @return The lookup map.
*/
public Map<String, StringLookup> getStringLookupMap() {
return stringLookupMap;
@@ -120,7 +120,7 @@ class InterpolatorStringLookup extends AbstractStringLookup {
*
* @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 @@ final class JavaPlatformStringLookup extends AbstractStringLookup {
* 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 @@ final class MapStringLookup<V> implements StringLookup {
/**
* 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 @@ final class MapStringLookup<V> implements StringLookup {
*
* @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 @@ import org.apache.commons.text.StringSubstitutor;
* 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 @@ public interface StringLookup {
*
* @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 da61c6f..693eedb 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 @@ package org.apache.commons.text.lookup;
import java.util.Map;
+import org.apache.commons.text.StringSubstitutor;
+
/**
* Provides access to lookups defined in this package.
* <p>
@@ -270,8 +272,7 @@ public final class StringLookupFactory {
/**
* 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) {
@@ -285,10 +286,26 @@ public final class StringLookupFactory {
}
/**
- * 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() {
@@ -296,10 +313,26 @@ public final class StringLookupFactory {
}
/**
- * 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() {
@@ -307,10 +340,26 @@ public final class StringLookupFactory {
}
/**
- * 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()}.
*/
@@ -320,9 +369,37 @@ public final class StringLookupFactory {
}
/**
- * 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() {
@@ -332,8 +409,25 @@ public final class StringLookupFactory {
/**
* 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;
@@ -342,8 +436,26 @@ public final class StringLookupFactory {
/**
* 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;
@@ -352,13 +464,24 @@ public final class StringLookupFactory {
/**
* 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() {
@@ -367,6 +490,26 @@ public final class StringLookupFactory {
/**
* 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.
*/
@@ -381,12 +524,9 @@ public final class StringLookupFactory {
* {@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
*/
@@ -398,10 +538,8 @@ public final class StringLookupFactory {
/**
* 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) {
@@ -411,8 +549,7 @@ public final class StringLookupFactory {
/**
* 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) {
@@ -434,7 +571,7 @@ public final class StringLookupFactory {
* <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;
@@ -448,7 +585,7 @@ public final class StringLookupFactory {
* <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;
@@ -457,10 +594,8 @@ public final class StringLookupFactory {
/**
* 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) {
@@ -470,7 +605,7 @@ public final class StringLookupFactory {
/**
* 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;
@@ -485,7 +620,7 @@ public final class StringLookupFactory {
* For example: "com/domain/document.properties:Key".
* </p>
*
- * @return the PropertiesStringLookup singleton instance.
+ * @return The PropertiesStringLookup singleton instance.
* @since 1.5
*/
public StringLookup propertiesStringLookup() {
@@ -501,7 +636,7 @@ public final class StringLookupFactory {
* For example: "com.domain.messages:MyKey".
* </p>
*
- * @return the ResourceBundleStringLookup singleton instance.
+ * @return The ResourceBundleStringLookup singleton instance.
*/
public StringLookup resourceBundleStringLookup() {
return ResourceBundleStringLookup.INSTANCE;
@@ -516,8 +651,7 @@ public final class StringLookupFactory {
* 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
*/
@@ -534,7 +668,7 @@ public final class StringLookupFactory {
* For example: "javascript:3+4".
* </p>
*
- * @return the ScriptStringLookup singleton instance.
+ * @return The ScriptStringLookup singleton instance.
* @since 1.5
*/
public StringLookup scriptStringLookup() {
@@ -544,7 +678,7 @@ public final class StringLookupFactory {
/**
* 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;
@@ -559,7 +693,7 @@ public final class StringLookupFactory {
* 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() {
@@ -575,7 +709,7 @@ public final class StringLookupFactory {
* 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() {
@@ -595,7 +729,7 @@ public final class StringLookupFactory {
* "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() {
@@ -611,7 +745,7 @@ public final class StringLookupFactory {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ abstract class AbstractStringMatcher implements StringMatcher {
* 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 @@ public interface StringMatcher {
* 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 @@ public final class StringMatcherFactory {
/**
* 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 @@ public final class StringMatcherFactory {
/**
* 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 @@ public class CosineSimilarity {
* @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 @@ public interface EditDistance<R> extends SimilarityScore<R> {
*
* @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 @@ public class EditDistanceFrom<R> {
* </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 @@ public class EditDistanceFrom<R> {
/**
* Gets the left parameter.
*
- * @return the left parameter
+ * @return The left parameter
*/
public CharSequence getLeft() {
return left;
@@ -103,7 +103,7 @@ public class EditDistanceFrom<R> {
/**
* 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 @@ public class FuzzyScore {
/**
* 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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
* 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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
/**
* 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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
/**
* 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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
*
* @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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
* 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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
* @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 @@ public class IntersectionSimilarity<T> implements SimilarityScore<IntersectionRe
*
* @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 @@ public class LevenshteinDetailedDistance implements EditDistance<LevenshteinResu
/**
* Gets the default instance.
*
- * @return the default instace
+ * @return The default instace
*/
public static LevenshteinDetailedDistance getDefaultInstance() {
return DEFAULT_INSTANCE;
@@ -118,7 +118,7 @@ public class LevenshteinDetailedDistance implements EditDistance<LevenshteinResu
/**
* 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 @@ public class LevenshteinDistance implements EditDistance<Integer> {
/**
* Gets the default instance.
*
- * @return the default instance
+ * @return The default instance
*/
public static LevenshteinDistance getDefaultInstance() {
return DEFAULT_INSTANCE;
@@ -126,7 +126,7 @@ public class LevenshteinDistance implements EditDistance<Integer> {
/**
* 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 @@ public class LongestCommonSubsequence implements SimilarityScore<Integer> {
*
* @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 @@ public class LongestCommonSubsequence implements SimilarityScore<Integer> {
*
* @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 @@ public interface SimilarityScore<R> {
*
* @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 @@ public class SimilarityScoreFrom<R> {
* </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 @@ public class SimilarityScoreFrom<R> {
/**
* Gets the left parameter.
*
- * @return the left parameter
+ * @return The left parameter
*/
public CharSequence getLeft() {
return left;
@@ -103,7 +103,7 @@ public class SimilarityScoreFrom<R> {
/**
* 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 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
*
* @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 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
*
* @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 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
* 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 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
* 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 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
*
* @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 @@ public class NumericEntityEscaper extends CodePointTranslator {
* <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 @@ public class NumericEntityEscaper extends CodePointTranslator {
* <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 @@ public class NumericEntityEscaper extends CodePointTranslator {
*
* @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 @@ public class NumericEntityEscaper extends CodePointTranslator {
*
* @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 @@ abstract class SinglePassTranslator extends CharSequenceTranslator {
/**
* 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 @@ public class UnicodeEscaper extends CodePointTranslator {
* <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 @@ public class UnicodeEscaper extends CodePointTranslator {
* <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 @@ public class UnicodeEscaper extends CodePointTranslator {
*
* @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 @@ public class UnicodeEscaper extends CodePointTranslator {
*
* @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 @@ public class UnicodeEscaper extends CodePointTranslator {
*
* @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/StringSubstitutorWithInterpolatorStringLookupTest.java b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
index e7e35e3..f05b2c7 100644
--- a/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
+++ b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
@@ -61,7 +61,7 @@ public class StringSubstitutorWithInterpolatorStringLookupTest {
@Test
public void testDefaultValueForMissingKeyInResourceBundle() {
final StringLookup interpolatorStringLookup = StringLookupFactory.INSTANCE.interpolatorStringLookup(
- StringLookupFactory.INSTANCE.resourceBundleStringLookup("testResourceBundleLookup"));
+ StringLookupFactory.INSTANCE.resourceBundleStringLookup("testResourceBundleLookup"));
assertEquals("${missingKey:-defaultValue}", interpolatorStringLookup.lookup("keyWithMissingKey"));
final StringSubstitutor stringSubstitutor = new StringSubstitutor(interpolatorStringLookup);
// The following would throw a MissingResourceException before TEXT-165.
@@ -69,11 +69,19 @@ public class StringSubstitutorWithInterpolatorStringLookupTest {
}
@Test
- void testJavaScript() {
+ void testAll() {
+ // @formatter:off
+ StringSubstitutor.createInterpolator().replace(
+ "OS name: ${sys:os.name}, " +
+ "3 + 4 = ${script:javascript:3 + 4}");
+ // @formatter:on
+ }
+
+ @Test
+ public void testJavaScript() {
Assertions.assertEquals("Hello World!",
StringSubstitutor.createInterpolator().replace("${script:javascript:\"Hello World!\"}"));
- Assertions.assertEquals("7",
- StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}"));
+ Assertions.assertEquals("7", StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}"));
}
@Test
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 class DateStringLookupTest {
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());
[commons-text] 05/05: Expand Javadoc for StringSubstitutor and
friends.
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit 42e7659eef2f66741acab5a1d16489e6361ea033
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 4 11:35:58 2019 -0400
Expand Javadoc for StringSubstitutor and friends.
---
src/changes/changes.xml | 2 ++
1 file changed, 2 insertions(+)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index b0b2a60..8d1527e 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -50,6 +50,8 @@ The <action> type attribute can be add,update,fix,remove.
<action issue="TEXT-168" type="fix" dev="ggregory" due-to="luksan47">(doc) Fixed wrong value for Jaro-Winkler example #117</action>
<action issue="TEXT-169" type="add" dev="ggregory" due-to="Gary Gregory">Add helper factory method org.apache.commons.text.StringSubstitutor.createInterpolator().</action>
<action issue="TEXT-170" type="add" dev="ggregory" due-to="Gary Gregory">Add String lookup for host names and IP addresses (DnsStringLookup).</action>
+ <action type="update" dev="ggregory" due-to="Gary Gregory">Expand Javadoc for StringSubstitutor and friends.</action>
+
</release>
<release version="1.7" date="2019-06-30" description="Release 1.7">
[commons-text] 02/05: Sort members.
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit 45eb67d2782197b89e5db0423ec8569c2e63ad4c
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 4 10:28:45 2019 -0400
Sort members.
---
src/main/java/org/apache/commons/text/StringSubstitutor.java | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/src/main/java/org/apache/commons/text/StringSubstitutor.java b/src/main/java/org/apache/commons/text/StringSubstitutor.java
index 6764fe6..535cd78 100644
--- a/src/main/java/org/apache/commons/text/StringSubstitutor.java
+++ b/src/main/java/org/apache/commons/text/StringSubstitutor.java
@@ -184,6 +184,11 @@ public class StringSubstitutor {
/**
* Creates a new instance using the interpolator string lookup
* {@link StringLookupFactory#interpolatorStringLookup()}.
+ * <p>
+ * This StringSubstitutor lets you perform substituions like:
+ * </p>
+ * <pre>
+ * </pre>
*
* @return a new instance using the interpolator string lookup.
* @see StringLookupFactory#interpolatorStringLookup()
[commons-text] 01/05: Sort members.
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit d69181fe75d9cfa4542d565f4ca4af4cd8f8d013
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 4 10:28:31 2019 -0400
Sort members.
---
...tringSubstitutorWithInterpolatorStringLookupTest.java | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
index e70e953..e7e35e3 100644
--- a/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
+++ b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java
@@ -69,6 +69,14 @@ public class StringSubstitutorWithInterpolatorStringLookupTest {
}
@Test
+ void testJavaScript() {
+ Assertions.assertEquals("Hello World!",
+ StringSubstitutor.createInterpolator().replace("${script:javascript:\"Hello World!\"}"));
+ Assertions.assertEquals("7",
+ StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}"));
+ }
+
+ @Test
public void testLocalHostLookup_Address() throws UnknownHostException {
final StringSubstitutor strSubst = StringSubstitutor.createInterpolator();
Assertions.assertEquals(InetAddress.getLocalHost().getHostAddress(), strSubst.replace("${localhost:address}"));
@@ -101,14 +109,6 @@ public class StringSubstitutorWithInterpolatorStringLookupTest {
}
@Test
- void testJavaScript() {
- Assertions.assertEquals("Hello World!",
- StringSubstitutor.createInterpolator().replace("${script:javascript:\"Hello World!\"}"));
- Assertions.assertEquals("7",
- StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}"));
- }
-
- @Test
public void testSystemProperty() {
final StringSubstitutor strSubst = StringSubstitutor.createInterpolator();
final String spKey = "user.name";
[commons-text] 04/05: [TEXT-170] Add String lookup for host names
and IP addresses (#118)
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit 3ba2268249138c597f8eb071c25fceeb717ae144
Merge: 7576289 d81879e
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 4 11:34:31 2019 -0400
[TEXT-170] Add String lookup for host names and IP addresses (#118)
Merge remote-tracking branch 'origin/master'.
src/changes/changes.xml | 1 +
.../commons/text/lookup/DefaultStringLookup.java | 7 ++
.../commons/text/lookup/DnsStringLookup.java | 85 ++++++++++++++++++++++
.../commons/text/lookup/InetAddressKeys.java | 44 +++++++++++
.../commons/text/lookup/LocalHostStringLookup.java | 6 +-
.../commons/text/lookup/StringLookupFactory.java | 28 +++++++
...ubstitutorWithInterpolatorStringLookupTest.java | 67 +++++++++++++----
.../text/lookup/DefaultStringLookupTest.java | 1 +
.../commons/text/lookup/DnsStringLookupTest.java | 71 ++++++++++++++++++
.../text/lookup/StringLookupFactoryTest.java | 2 +
10 files changed, 295 insertions(+), 17 deletions(-)
diff --cc src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
index 693eedb,8fbf9b4..7cfc90b
--- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
+++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
@@@ -592,10 -468,27 +605,25 @@@ public final class StringLookupFactory
}
/**
+ * Returns the DnsStringLookup singleton instance where the lookup key is one of:
+ * <ul>
+ * <li><b>name</b>: for the local host name, for example {@code EXAMPLE} but also {@code EXAMPLE.apache.org}.</li>
+ * <li><b>canonical-name</b>: for the local canonical host name, for example {@code EXAMPLE.apache.org}.</li>
+ * <li><b>address</b>: for the local host address, for example {@code 192.168.56.1}.</li>
+ * </ul>
+ *
+ * @return the DateStringLookup singleton instance.
+ * @since 1.8
+ */
+ public StringLookup dnsStringLookup() {
+ return DnsStringLookup.INSTANCE;
+ }
+
+ /**
* 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) {