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 <[email protected]> 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());
