* Convert from one alphabet to another, with the possibility of leaving certain * characters unencoded. *
* ** The target and 'do not encode' languages must be in the Unicode BMP, but the * source language does not. *
* ** The encoding will all be of a fixed length, except for the 'do not encode' * chars, which will be of length 1 *
* *
* Character[] originals; // a, b, c, d
* Character[] encoding; // 0, 1, d
* Character[] doNotEncode; // d
*
* AlphabetConverter ac = AlphabetConverter.createConverterFromChars(originals,
* encoding, doNotEncode);
*
* ac.encode("a"); // 00
* ac.encode("b"); // 01
* ac.encode("c"); // 0d
* ac.encode("d"); // d
* ac.encode("abcd"); // 00010dd
*
*
* * #ThreadSafe# AlphabetConverter class methods are thread-safe as they do not * change internal state. *
* * @since 1.0 */ public final class AlphabetConverter { /** * Arrow constant, used for converting the object into a string. */ private static final String ARROW = " -> "; /** * Creates new String that contains just the given code point. * * @param i code point. * @return a new string with the new code point. * @see "http://www.oracle.com/us/technologies/java/supplementary-142654.html" */ private static String codePointToString(final int i) { if (Character.charCount(i) == 1) { return String.valueOf((char) i); } return new String(Character.toChars(i)); } /** * Converts characters to integers. * * @param chars array of characters. * @return an equivalent array of integers. */ private static Integer[] convertCharsToIntegers(final Character[] chars) { if (ArrayUtils.isEmpty(chars)) { return ArrayUtils.EMPTY_INTEGER_OBJECT_ARRAY; } final Integer[] integers = new Integer[chars.length]; Arrays.setAll(integers, i -> (int) chars[i]); return integers; } /** * Creates an alphabet converter, for converting from the original alphabet, to the encoded alphabet, while leaving the characters in doNotEncode * as they are (if possible). * ** Duplicate letters in either original or encoding will be ignored. *
* * @param original an array of ints representing the original alphabet in code points. * @param encoding an array of ints representing the alphabet to be used for encoding, in code points. * @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. * @throws IllegalArgumentException if an AlphabetConverter cannot be constructed. */ public static AlphabetConverter createConverter( final Integer[] original, final Integer[] encoding, final Integer[] doNotEncode) { final SetDuplicate letters in either original or encoding will be ignored.
* * @param original an array of chars representing the original alphabet * @param encoding an array of chars representing the alphabet to be used * for encoding * @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 * @throws IllegalArgumentException if an AlphabetConverter cannot be * constructed */ public static AlphabetConverter createConverterFromChars( final Character[] original, final Character[] encoding, final Character[] doNotEncode) { return createConverter( convertCharsToIntegers(original), convertCharsToIntegers(encoding), convertCharsToIntegers(doNotEncode)); } /** * Creates a new converter from a map. * * @param originalToEncoded a map returned from getOriginalToEncoded(). * @return The reconstructed AlphabetConverter. * @see AlphabetConverter#getOriginalToEncoded() */ public static AlphabetConverter createConverterFromMap(final Map* Defines a class as a builder following the Builder design pattern. Builders are capable of creating and configuring objects or results that normally * take multiple steps to construct or are very complex to derive. *
** The builder interface defines a single method, {@link #get()}, that classes must implement. The result of this method should be the final configured object * or result after all building operations are performed. *
** It is a recommended practice that the methods supplied to configure the object or result being built return a reference to {@code this} so that method calls * can be chained together. *
* ** Example Builder: *
* *
*
* class FontBuilder implements Builder<Font> {
* private Font font;
*
* public FontBuilder(String fontName) {
* this.font = new Font(fontName, Font.PLAIN, 12);
* }
*
* public FontBuilder bold() {
* this.font = this.font.deriveFont(Font.BOLD);
* return this; // Reference returned so calls can be chained
* }
*
* public FontBuilder size(float pointSize) {
* this.font = this.font.deriveFont(pointSize);
* return this; // Reference returned so calls can be chained
* }
*
* // Other Font construction methods
*
* public Font build() {
* return this.font;
* }
* }
*
*
*
* Example Builder Usage:
*
*
* {@code
* Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF)
* .bold()
* .size(14.0f)
* .get();
* }
*
*
*
* @param This class tries to handle {@code null} input gracefully. * An exception will not be thrown for a {@code null} input. * Each method documents its behavior in more detail.
* * @since 1.2 */ public class CaseUtils { /** * Converts all the delimiter separated words in a String into camelCase, * that is each word is made up of a title case character and then a series of * lowercase characters. * *The delimiters represent a set of characters understood to separate words. * The first non-delimiter character after a delimiter will be capitalized. The first String * character may or may not be capitalized and it's determined by the user input for capitalizeFirstLetter * variable.
* *A {@code null} input String returns {@code null}.
* *A input string with only delimiter characters returns {@code ""}.
* * Capitalization uses the Unicode title case, normally equivalent to * upper case and cannot perform locale-sensitive mappings. * *
* CaseUtils.toCamelCase(null, false) = null
* CaseUtils.toCamelCase("", false, *) = ""
* CaseUtils.toCamelCase(*, false, null) = *
* CaseUtils.toCamelCase(*, true, new char[0]) = *
* CaseUtils.toCamelCase("To.Camel.Case", false, new char[]{'.'}) = "toCamelCase"
* CaseUtils.toCamelCase(" to @ Camel case", true, new char[]{'@'}) = "ToCamelCase"
* CaseUtils.toCamelCase(" @to @ Camel case", false, new char[]{'@'}) = "toCamelCase"
* CaseUtils.toCamelCase(" @", false, new char[]{'@'}) = ""
*
*
* @param str the String to be converted to camelCase, may be null
* @param capitalizeFirstLetter boolean that determines if the first character of first word should be title case.
* @param delimiters set of characters to determine capitalization, null and/or empty array means whitespace
* @return camelCase of String, {@code null} if null String input
*/
public static String toCamelCase(String str, final boolean capitalizeFirstLetter, final char... delimiters) {
if (StringUtils.isEmpty(str)) {
return str;
}
str = str.toLowerCase();
final int strLen = str.length();
final int[] newCodePoints = new int[strLen];
int outOffset = 0;
final SetThis constructor is public to permit tools that require a JavaBean * instance to operate.
*/ public CaseUtils() { } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/CharacterPredicate.java 0000664 0000000 0000000 00000002363 15114327406 0033140 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; /** * A predicate for selecting code points. Implementations of this interface must be thread safe. * * @since 1.0 */ public interface CharacterPredicate { /** * Tests the code point with this predicate. * * @param codePoint the code point to test. * @return {@code true} if the code point matches the predicate, {@code false} otherwise. * @since 1.0 */ boolean test(int codePoint); } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/CharacterPredicates.java 0000664 0000000 0000000 00000006117 15114327406 0033324 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; /** * Commonly used implementations of {@link CharacterPredicate}. Per the interface * requirements, all implementations are thread safe. * * @since 1.0 */ public enum CharacterPredicates implements CharacterPredicate { /** * Tests code points against {@link Character#isLetter(int)}. * * @since 1.0 */ LETTERS { @Override public boolean test(final int codePoint) { return Character.isLetter(codePoint); } }, /** * Tests code points against {@link Character#isDigit(int)}. * * @since 1.0 */ DIGITS { @Override public boolean test(final int codePoint) { return Character.isDigit(codePoint); } }, /** * Tests if the code points represents a number between 0 and 9. * * @since 1.2 */ ARABIC_NUMERALS { @Override public boolean test(final int codePoint) { return codePoint >= '0' && codePoint <= '9'; } }, /** * Tests if the code points represents a letter between a and z. * * @since 1.2 */ ASCII_LOWERCASE_LETTERS { @Override public boolean test(final int codePoint) { return codePoint >= 'a' && codePoint <= 'z'; } }, /** * Tests if the code points represents a letter between A and Z. * * @since 1.2 */ ASCII_UPPERCASE_LETTERS { @Override public boolean test(final int codePoint) { return codePoint >= 'A' && codePoint <= 'Z'; } }, /** * Tests if the code points represents a letter between a and Z. * * @since 1.2 */ ASCII_LETTERS { @Override public boolean test(final int codePoint) { return ASCII_LOWERCASE_LETTERS.test(codePoint) || ASCII_UPPERCASE_LETTERS.test(codePoint); } }, /** * Tests if the code points represents a letter between a and Z or a number between 0 and 9. * * @since 1.2 */ ASCII_ALPHA_NUMERALS { @Override public boolean test(final int codePoint) { return ASCII_LOWERCASE_LETTERS.test(codePoint) || ASCII_UPPERCASE_LETTERS.test(codePoint) || ARABIC_NUMERALS.test(codePoint); } } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/CompositeFormat.java 0000664 0000000 0000000 00000007064 15114327406 0032541 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.text.FieldPosition; import java.text.Format; import java.text.ParseException; import java.text.ParsePosition; /** * Formats using one formatter and parses using a different formatter. An * example of use for this would be a webapp where data is taken in one way and * stored in a database another way. * * @since 1.0 */ public class CompositeFormat extends Format { /** * Required for serialization support. * * @see java.io.Serializable */ private static final long serialVersionUID = -4329119827877627683L; /** The parser to use. */ private final Format parser; /** The formatter to use. */ private final Format formatter; /** * Constructs a format that points its parseObject method to one implementation * and its format method to another. * * @param parser implementation. * @param formatter implementation. */ public CompositeFormat(final Format parser, final Format formatter) { this.parser = parser; this.formatter = formatter; } /** * Formats the input. * * @param obj the object to format. * @param toAppendTo the {@link StringBuffer} to append to. * @param pos the FieldPosition to use (or ignore). * @return {@code toAppendTo}. * @see Format#format(Object, StringBuffer, FieldPosition) */ @Override // Therefore has to use StringBuffer public StringBuffer format(final Object obj, final StringBuffer toAppendTo, final FieldPosition pos) { return formatter.format(obj, toAppendTo, pos); } /** * Gets the parser Format implementation. * * @return formatter Format implementation */ public Format getFormatter() { return this.formatter; } /** * Gets the parser Format implementation. * * @return parser Format implementation */ public Format getParser() { return this.parser; } /** * Parses the input. * * @param source the String source. * @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. * @see Format#parseObject(String, ParsePosition) */ @Override public Object parseObject(final String source, final ParsePosition pos) { return parser.parseObject(source, pos); } /** * Parses and then reformats a String. * * @param input String to reformat. * @return A reformatted String. * @throws ParseException thrown by parseObject(String) call. */ public String reformat(final String input) throws ParseException { return format(parseObject(input)); } } ExtendedMessageFormat.java 0000664 0000000 0000000 00000045736 15114327406 0033575 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.text.Format; import java.text.MessageFormat; import java.text.ParsePosition; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.HashMap; import java.util.Locale; import java.util.Locale.Category; import java.util.Map; import java.util.Objects; import org.apache.commons.lang3.StringUtils; import org.apache.commons.text.matcher.StringMatcherFactory; /** * Extends {@link java.text.MessageFormat} to allow pluggable/additional formatting * options for embedded format elements. Client code should specify a registry * of {@code FormatFactory} instances associated with {@code String} * format names. This registry will be consulted when the format elements are * parsed from the message pattern. In this way custom patterns can be specified, * and the formats supported by {@link java.text.MessageFormat} can be overridden * at the format and/or format style level (see MessageFormat). A "format element" * embedded in the message pattern is specified (()? signifies optionality):* format-name and format-style values are trimmed of surrounding whitespace * in the manner of {@link java.text.MessageFormat}. If format-name denotes * {@code FormatFactory formatFactoryInstance} in {@code registry}, a {@code Format} * matching format-name and format-style is requested from * {@code formatFactoryInstance}. If this is successful, the {@code Format} * found is used for this format element. *
* *NOTICE: The various subformat mutator methods are considered unnecessary; they exist on the parent * class to allow the type of customization which it is the job of this class to provide in * a configurable fashion. These methods have thus been disabled and will throw * {@code UnsupportedOperationException} if called. *
* *Limitations inherited from {@link java.text.MessageFormat}:
** The {@link Formattable} interface provides basic control over formatting when using a {@code Formatter}. It is primarily concerned with numeric precision and * padding, and is not designed to allow generalized alternate formats. *
* * @since 1.0 */ public class FormattableUtils { /** * A format that simply outputs the value as a string. */ private static final String SIMPLEST_FORMAT = "%s"; /** * Handles the common {@code Formattable} operations of truncate-pad-append, with no ellipsis on precision overflow, and padding width underflow with * spaces. * * @param seq the string to handle, not null. * @param formatter the destination formatter, not null. * @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. */ public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, final int precision) { return append(seq, formatter, flags, width, precision, ' ', null); } /** * Handles the common {@link Formattable} operations of truncate-pad-append, with no ellipsis on precision overflow. * * @param seq the string to handle, not null. * @param formatter the destination formatter, not null. * @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}. * @param padChar the pad character to use. * @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) { return append(seq, formatter, flags, width, precision, padChar, null); } /** * Handles the common {@link Formattable} operations of truncate-pad-append. * * @param seq the string to handle, not null. * @param formatter the destination formatter, not null. * @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}. * @param padChar the pad character to use. * @param truncateEllipsis the ellipsis to use when precision dictates truncation, null or empty causes a hard truncation. * @return The {@code formatter} instance, not null. * @throws IllegalArgumentException if {@code ellipsis.length() > precision}, given that {@code ellipsis} is not null and {@code precision >= 0}. */ public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, final int precision, final char padChar, final CharSequence truncateEllipsis) { if (!(truncateEllipsis == null || precision < 0 || truncateEllipsis.length() <= precision)) { throw new IllegalArgumentException( String.format("Specified ellipsis '%s' exceeds precision of %s", truncateEllipsis, precision)); } final StringBuilder buf = new StringBuilder(seq); if (precision >= 0 && precision < seq.length()) { final CharSequence ellipsis; if (truncateEllipsis == null) { ellipsis = StringUtils.EMPTY; } else { ellipsis = truncateEllipsis; } buf.replace(precision - ellipsis.length(), seq.length(), ellipsis.toString()); } final boolean leftJustify = (flags & LEFT_JUSTIFY) == LEFT_JUSTIFY; for (int i = buf.length(); i < width; i++) { buf.insert(leftJustify ? i : 0, padChar); } formatter.format(buf.toString()); return formatter; } /** * Handles the common {@link Formattable} operations of truncate-pad-append, padding width underflow with spaces. * * @param seq the string to handle, not null. * @param formatter the destination formatter, not null. * @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}. * @param ellipsis the ellipsis to use when precision dictates truncation, null or empty causes a hard truncation.. * @return The {@code formatter} instance, not null * @throws IllegalArgumentException if {@code ellipsis.length() > precision}, given that {@code ellipsis} is not null and {@code precision >= 0}. */ public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, final int precision, final CharSequence ellipsis) { return append(seq, formatter, flags, width, precision, ' ', ellipsis); } /** * Gets the default formatted representation of the specified {@code Formattable}. * * @param formattable the instance to convert to a string, not null. * @return The resulting string, not null. */ public static String toString(final Formattable formattable) { return String.format(SIMPLEST_FORMAT, formattable); } /** * {@code FormattableUtils} instances should NOT be constructed in standard programming. Instead, the methods of the class should be invoked statically. * ** This constructor is public to permit tools that require a JavaBean instance to operate. *
*/ public FormattableUtils() { } } RandomStringGenerator.java 0000664 0000000 0000000 00000047171 15114327406 0033630 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.util.ArrayList; import java.util.Collections; import java.util.HashSet; import java.util.List; import java.util.Set; import java.util.concurrent.ThreadLocalRandom; import java.util.function.IntUnaryOperator; import org.apache.commons.lang3.ArrayUtils; import org.apache.commons.lang3.StringUtils; import org.apache.commons.lang3.Validate; /** * Generates random Unicode strings containing the specified number of code points. Instances are created using a builder class, which allows the callers to * define the properties of the generator. See the documentation for the {@link Builder} class to see available properties. * *
* // Generates a 20 code point string, using only the letters a-z
* RandomStringGenerator generator = RandomStringGenerator.builder().withinRange('a', 'z').build();
* String randomLetters = generator.generate(20);
*
*
* // Using Apache Commons RNG for randomness
* UniformRandomProvider rng = RandomSource.create(...);
* // Generates a 20 code point string, using only the letters a-z
* RandomStringGenerator generator = RandomStringGenerator.builder()
* .withinRange('a', 'z')
* .usingRandom(rng::nextInt)
* .build();
* String randomLetters = generator.generate(20);
*
* * {@code RandomStringGenerator} instances are thread-safe when using the default random number generator (RNG). If a custom RNG is set by calling the method * {@link Builder#usingRandom(TextRandomProvider) Builder.usingRandom(TextRandomProvider)}, thread-safety must be ensured externally. *
* * @since 1.1 */ public final class RandomStringGenerator { /** * A builder for generating {@code RandomStringGenerator} instances. * ** The behavior of a generator is controlled by properties set by this builder. Each property has a default value, which can be overridden by calling the * methods defined in this class, prior to calling {@link #build()}. *
** All the property setting methods return the {@code Builder} instance to allow for method chaining. *
** The minimum and maximum code point values are defined using {@link #withinRange(int, int)}. The default values are {@code 0} and * {@link Character#MAX_CODE_POINT} respectively. *
** The source of randomness can be set using {@link #usingRandom(TextRandomProvider)}, otherwise {@link ThreadLocalRandom} is used. *
** The type of code points returned can be filtered using {@link #filteredBy(CharacterPredicate...)}, which defines a collection of tests that are applied * to the randomly generated code points. The code points will only be included in the result if they pass at least one of the tests. Some commonly used * predicates are provided by the {@link CharacterPredicates} enum. *
** This class is not thread safe. *
* * @since 1.1 */ public static class Builder implements org.apache.commons.text.Builder* Passing {@code null} or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method * will replace the previously stored predicates. *
* * @param predicates the predicates, may be {@code null} or empty. * @return {@code this} instance. */ public Builder filteredBy(final CharacterPredicate... predicates) { if (ArrayUtils.isEmpty(predicates)) { inclusivePredicates = null; return this; } if (inclusivePredicates == null) { inclusivePredicates = new HashSet<>(); } else { inclusivePredicates.clear(); } Collections.addAll(inclusivePredicates, predicates); return this; } /** * Builds a new {@code RandomStringGenerator}. * * @return A new {@code RandomStringGenerator}. * @since 1.12.0 */ @Override public RandomStringGenerator get() { return new RandomStringGenerator(this); } private void initCharList() { if (!accumulate) { characterSet = new HashSet<>(); } } /** * Limits the characters in the generated string to those who match at supplied list of Character. * ** Passing {@code null} or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method * will replace the previously stored Character. *
* * @param chars set of predefined Characters for random string generation the Character can be, may be {@code null} or empty. * @return {@code this} instance. * @since 1.2 */ public Builder selectFrom(final char... chars) { initCharList(); if (chars != null) { for (final char c : chars) { characterSet.add(c); } } return this; } /** * Sets whether calls accumulates the source of provided characters. The default is {@code false}. * *
* {@code
* RandomStringGenerator gen = RandomStringGenerator.builder()
* .setAccumulate(true)
* .withinRange(new char[][] { { 'a', 'z' }, { 'A', 'Z' }, { '0', '9' } })
* .selectFrom('!', '"', '#', '$', '&', '\'', '(', ')', ',', '.', ':', ';', '?', '@', '[',
* '\\', ']', '^', '_', '`', '{', '|', '}', '~') // punctuation
* // additional builder calls as needed
* .build();
* }
*
*
* @param accumulate whether calls accumulates the source of provided characters. The default is {@code false}.
* @return {@code this} instance.
* @since 1.14.0
*/
public Builder setAccumulate(final boolean accumulate) {
this.accumulate = accumulate;
return this;
}
/**
* Overrides the default source of randomness. It is highly recommended that a random number generator library like
* Apache Commons RNG be used to provide the random number generation.
*
* * {@link TextRandomProvider} is a functional interface and need not be explicitly implemented: *
* *
* {@code
* UniformRandomProvider rng = RandomSource.create(...);
* RandomStringGenerator gen = RandomStringGenerator.builder()
* .usingRandom(rng::nextInt)
* // additional builder calls as needed
* .build();
* }
*
*
* * Passing {@code null} to this method will revert to the default source of randomness. *
* * @param random the source of randomness, may be {@code null}. * @return {@code this} instance. * @since 1.14.0 */ public Builder usingRandom(final IntUnaryOperator random) { this.random = random; return this; } /** * Overrides the default source of randomness. It is highly recommended that a random number generator library like * Apache Commons RNG be used to provide the random number generation. * ** {@link TextRandomProvider} is a functional interface and need not be explicitly implemented: *
* *
* {@code
* UniformRandomProvider rng = RandomSource.create(...);
* RandomStringGenerator gen = RandomStringGenerator.builder()
* .usingRandom(rng::nextInt)
* // additional builder calls as needed
* .build();
* }
*
*
* * Passing {@code null} to this method will revert to the default source of randomness. *
* * @param random the source of randomness, may be {@code null}. * @return {@code this} instance. */ public Builder usingRandom(final TextRandomProvider random) { this.random = random; return this; } /** * Sets the array of minimum and maximum char allowed in the generated string. * * For example: * *
* {@code
* char[][] pairs = { { '0', '9' } };
* char[][] pairs = { { 'a', 'z' } };
* char[][] pairs = { { 'a', 'z' }, { '0', '9' } };
* }
*
*
* @param pairs array of characters array, expected is to pass min, max pairs through this arg.
* @return {@code this} instance.
*/
public Builder withinRange(final char[]... pairs) {
initCharList();
if (pairs != null) {
for (final char[] pair : pairs) {
Validate.isTrue(pair.length == 2, "Each pair must contain minimum and maximum code point");
final int minimumCodePoint = pair[0];
final int maximumCodePoint = pair[1];
Validate.isTrue(minimumCodePoint <= maximumCodePoint, "Minimum code point %d is larger than maximum code point %d", minimumCodePoint,
maximumCodePoint);
for (int index = minimumCodePoint; index <= maximumCodePoint; index++) {
characterSet.add((char) index);
}
}
}
return this;
}
/**
* Sets the minimum and maximum code points allowed in the generated string.
*
* @param minimumCodePoint the smallest code point allowed (inclusive).
* @param maximumCodePoint the largest code point allowed (inclusive).
* @return {@code this} instance.
* @throws IllegalArgumentException if {@code maximumCodePoint >} {@link Character#MAX_CODE_POINT}.
* @throws IllegalArgumentException if {@code minimumCodePoint < 0}.
* @throws IllegalArgumentException if {@code minimumCodePoint > maximumCodePoint}.
*/
public Builder withinRange(final int minimumCodePoint, final int maximumCodePoint) {
Validate.isTrue(minimumCodePoint <= maximumCodePoint, "Minimum code point %d is larger than maximum code point %d", minimumCodePoint,
maximumCodePoint);
Validate.isTrue(minimumCodePoint >= 0, "Minimum code point %d is negative", minimumCodePoint);
Validate.isTrue(maximumCodePoint <= Character.MAX_CODE_POINT, "Value %d is larger than Character.MAX_CODE_POINT.", maximumCodePoint);
this.minimumCodePoint = minimumCodePoint;
this.maximumCodePoint = maximumCodePoint;
return this;
}
}
/**
* Constructs a new builder.
*
* @return a new builder.
* @since 1.11.0
*/
public static Builder builder() {
return new Builder();
}
/**
* The smallest allowed code point (inclusive).
*/
private final int minimumCodePoint;
/**
* The largest allowed code point (inclusive).
*/
private final int maximumCodePoint;
/**
* Filters for code points.
*/
private final Set* Code points are randomly selected between the minimum and maximum values defined in the generator. Surrogate and private use characters are not returned, * although the resulting string may contain pairs of surrogates that together encode a supplementary character. *
** Note: the number of {@code char} code units generated will exceed {@code length} if the string contains supplementary characters. See the * {@link Character} documentation to understand how Java stores Unicode values. *
* * @param length the number of code points to generate. * @return The generated string. * @throws IllegalArgumentException if {@code length < 0}. */ public String generate(final int length) { if (length == 0) { return StringUtils.EMPTY; } Validate.isTrue(length > 0, "Length %d is smaller than zero.", length); final StringBuilder builder = new StringBuilder(length); long remaining = length; do { final int codePoint; if (characterList != null && !characterList.isEmpty()) { codePoint = generateRandomNumber(characterList); } else { codePoint = generateRandomNumber(minimumCodePoint, maximumCodePoint); } switch (Character.getType(codePoint)) { case Character.UNASSIGNED: case Character.PRIVATE_USE: case Character.SURROGATE: continue; default: } if (inclusivePredicates != null) { boolean matchedFilter = false; for (final CharacterPredicate predicate : inclusivePredicates) { if (predicate.test(codePoint)) { matchedFilter = true; break; } } if (!matchedFilter) { continue; } } builder.appendCodePoint(codePoint); remaining--; } while (remaining != 0); return builder.toString(); } /** * Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points. * * @param minLengthInclusive the minimum (inclusive) number of code points to generate. * @param maxLengthInclusive the maximum (inclusive) number of code points to generate. * @return The generated string. * @throws IllegalArgumentException if {@code minLengthInclusive < 0}, or {@code maxLengthInclusive < minLengthInclusive}. * @see RandomStringGenerator#generate(int) * @since 1.2 */ public String generate(final int minLengthInclusive, final int maxLengthInclusive) { Validate.isTrue(minLengthInclusive >= 0, "Minimum length %d is smaller than zero.", minLengthInclusive); Validate.isTrue(minLengthInclusive <= maxLengthInclusive, "Maximum length %d is smaller than minimum length %d.", maxLengthInclusive, minLengthInclusive); return generate(generateRandomNumber(minLengthInclusive, maxLengthInclusive)); } /** * Generates a random number within a range, using a {@link ThreadLocalRandom} instance or the user-supplied source of randomness. * * @param minInclusive the minimum value allowed. * @param maxInclusive the maximum value allowed. * @return The random number. */ private int generateRandomNumber(final int minInclusive, final int maxInclusive) { if (random != null) { return random.applyAsInt(maxInclusive - minInclusive + 1) + minInclusive; } return ThreadLocalRandom.current().nextInt(minInclusive, maxInclusive + 1); } /** * Generates a random number within a range, using a {@link ThreadLocalRandom} instance or the user-supplied source of randomness. * * @param characterList predefined char list. * @return The random number. */ private int generateRandomNumber(final List* The main differences from {@link StrBuilder} and {@link StringBuilder} are: *
** The aim has been to provide an API that mimics very closely what StringBuffer provides, but with additional methods. It should be noted that some edge cases, * with invalid indices or null input, have been altered - see individual methods. The biggest of these changes is that by default, null will not output the * text 'null'. This can be controlled by a property, {@link #setNullText(String)}. *
* * @since 1.0 * @deprecated Deprecated as of 1.3, use {@link TextStringBuilder} instead. This class will be removed in 2.0. */ @Deprecated public class StrBuilder implements CharSequence, Appendable, Serializable, Builder* By default, the new line is the system default from {@link System#lineSeparator()}. *
** The new line string can be changed using {@link #setNewLineText(String)}. For example, you can use this to force the output to always use Unix line * endings even when on Windows. *
* * @return {@code this} instance. * @see #getNewLineText() * @see #setNewLineText(String) */ public StrBuilder appendNewLine() { if (newLine == null) { append(System.lineSeparator()); return this; } return append(newLine); } /** * Appends this builder's null text to this builder. * * @return {@code this} instance. */ public StrBuilder appendNull() { if (nullText == null) { return this; } return append(nullText); } /** * Appends the pad character to the builder the specified number of times. * * @param length the length to append, negative means no append. * @param padChar the character to append. * @return {@code this} instance. */ public StrBuilder appendPadding(final int length, final char padChar) { if (length >= 0) { ensureCapacity(size + length); for (int i = 0; i < length; i++) { buffer[size++] = padChar; } } return this; } /** * Appends a separator if the builder is currently non-empty. The separator is appended using {@link #append(char)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (Iterator it = list.iterator(); it.hasNext();) {
* appendSeparator(',');
* append(it.next());
* }
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use. * @return {@code this} instance. */ public StrBuilder appendSeparator(final char separator) { if (isNotEmpty()) { append(separator); } return this; } /** * Appends one of both separators to the builder If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append the * standard-separator * * The separator is appended using {@link #append(char)}. * * @param standard the separator if builder is not empty. * @param defaultIfEmpty the separator if builder is empty. * @return {@code this} instance. */ public StrBuilder appendSeparator(final char standard, final char defaultIfEmpty) { if (isNotEmpty()) { append(standard); } else { append(defaultIfEmpty); } return this; } /** * Appends a separator to the builder if the loop index is greater than zero. The separator is appended using {@link #append(char)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (int i = 0; i < list.size(); i++) {
* appendSeparator(",", i);
* append(list.get(i));
* }
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use. * @param loopIndex the loop index. * @return {@code this} instance. */ public StrBuilder appendSeparator(final char separator, final int loopIndex) { if (loopIndex > 0) { append(separator); } return this; } /** * Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The separator is appended using * {@link #append(String)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (Iterator it = list.iterator(); it.hasNext();) {
* appendSeparator(",");
* append(it.next());
* }
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public StrBuilder appendSeparator(final String separator) { return appendSeparator(separator, null); } /** * Appends a separator to the builder if the loop index is greater than zero. Appending a null separator will have no effect. The separator is appended * using {@link #append(String)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (int i = 0; i < list.size(); i++) {
* appendSeparator(",", i);
* append(list.get(i));
* }
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use, null means no separator. * @param loopIndex the loop index. * @return {@code this} instance. */ public StrBuilder appendSeparator(final String separator, final int loopIndex) { if (separator != null && loopIndex > 0) { append(separator); } return this; } /** * Appends one of both separators to the StrBuilder. If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append * the standard-separator ** Appending a null separator will have no effect. The separator is appended using {@link #append(String)}. *
** This method is for example useful for constructing queries *
* *
* StrBuilder whereClause = new StrBuilder();
* if (searchCommand.getPriority() != null) {
* whereClause.appendSeparator(" and", " where");
* whereClause.append(" priority = ?")
* }
* if (searchCommand.getComponent() != null) {
* whereClause.appendSeparator(" and", " where");
* whereClause.append(" component = ?")
* }
* selectClause.append(whereClause)
*
*
* @param standard the separator if builder is not empty, null means no separator.
* @param defaultIfEmpty the separator if builder is empty, null means no separator.
* @return {@code this} instance.
*/
public StrBuilder appendSeparator(final String standard, final String defaultIfEmpty) {
final String str = isEmpty() ? defaultIfEmpty : standard;
if (str != null) {
append(str);
}
return this;
}
/**
* Appends current contents of this {@code StrBuilder} to the provided {@link Appendable}.
* * This method tries to avoid doing any extra copies of contents. *
* * @param appendable the appendable to append data to. * @throws IOException if an I/O error occurs. * @see #readFrom(Readable) */ public void appendTo(final Appendable appendable) throws IOException { if (appendable instanceof Writer) { ((Writer) appendable).write(buffer, 0, size); } else if (appendable instanceof StringBuilder) { ((StringBuilder) appendable).append(buffer, 0, size); } else if (appendable instanceof StringBuffer) { ((StringBuffer) appendable).append(buffer, 0, size); } else if (appendable instanceof CharBuffer) { ((CharBuffer) appendable).put(buffer, 0, size); } else { appendable.append(this); } } /** * Appends an iterable placing separators between each value, but not before the first or after the last. Appending a null iterable will have no effect. * Each object is appended using {@link #append(Object)}. * * @param iterable the iterable to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public StrBuilder appendWithSeparators(final Iterable iterable, final String separator) { if (iterable != null) { appendWithSeparators(iterable.iterator(), separator); } return this; } /** * Appends an iterator placing separators between each value, but not before the first or after the last. Appending a null iterator will have no effect. * Each object is appended using {@link #append(Object)}. * * @param iterator the iterator to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public StrBuilder appendWithSeparators(final Iterator iterator, final String separator) { if (iterator != null) { final String sep = Objects.toString(separator, StringUtils.EMPTY); while (iterator.hasNext()) { append(iterator.next()); if (iterator.hasNext()) { append(sep); } } } return this; } /** * Appends an array placing separators between each value, but not before the first or after the last. Appending a null array will have no effect. Each * object is appended using {@link #append(Object)}. * * @param array the array to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public StrBuilder appendWithSeparators(final Object[] array, final String separator) { if (array != null && array.length > 0) { final String sep = Objects.toString(separator, StringUtils.EMPTY); append(array[0]); for (int i = 1; i < array.length; i++) { append(sep); append(array[i]); } } return this; } /** * Gets the contents of this builder as a Reader. ** This method allows the contents of the builder to be read using any standard method that expects a Reader. *
** To use, simply create a {@code StrBuilder}, populate it with data, call {@code asReader}, and then read away. *
** The internal character array is shared between the builder and the reader. This allows you to append to the builder after creating the reader, and the * changes will be picked up. Note however, that no synchronization occurs, so you must perform all operations with the builder and the reader in one * thread. *
** The returned reader supports marking, and ignores the flush method. *
* * @return a reader that reads from this builder. */ public Reader asReader() { return new StrBuilderReader(); } /** * Creates a tokenizer that can tokenize the contents of this builder. ** This method allows the contents of this builder to be tokenized. The tokenizer will be setup by default to tokenize on space, tab, newline and form feed * (as per StringTokenizer). These values can be changed on the tokenizer class, before retrieving the tokens. *
** The returned tokenizer is linked to this builder. You may intermix calls to the builder and tokenizer within certain limits, however there is no * synchronization. Once the tokenizer has been used once, it must be {@link StrTokenizer#reset() reset} to pickup the latest changes in the builder. For * example: *
* *
* StrBuilder b = new StrBuilder();
* b.append("a b ");
* StrTokenizer t = b.asTokenizer();
* String[] tokens1 = t.getTokenArray(); // returns a,b
* b.append("c d ");
* String[] tokens2 = t.getTokenArray(); // returns a,b (c and d ignored)
* t.reset(); // reset causes builder changes to be picked up
* String[] tokens3 = t.getTokenArray(); // returns a,b,c,d
*
* * In addition to simply intermixing appends and tokenization, you can also call the set methods on the tokenizer to alter how it tokenizes. Just remember * to call reset when you want to pickup builder changes. *
** Calling {@link StrTokenizer#reset(String)} or {@link StrTokenizer#reset(char[])} with a non-null value will break the link with the builder. *
* * @return a tokenizer that is linked to this builder. */ public StrTokenizer asTokenizer() { return new StrBuilderTokenizer(); } /** * Gets this builder as a Writer that can be written to. ** This method allows you to populate the contents of the builder using any standard method that takes a Writer. *
** To use, simply create a {@code StrBuilder}, call {@code asWriter}, and populate away. The data is available at any time using the methods of the * {@code StrBuilder}. *
** The internal character array is shared between the builder and the writer. This allows you to intermix calls that append to the builder and write using * the writer and the changes will be occur correctly. Note however, that no synchronization occurs, so you must perform all operations with the builder and * the writer in one thread. *
** The returned writer ignores the close and flush methods. *
* * @return a writer that populates this builder. */ public Writer asWriter() { return new StrBuilderWriter(); } /** * Converts this instance to a String. * * @return This instance as a String. * @see #toString() * @deprecated Use {@link #get()}. */ @Deprecated @Override public String build() { return toString(); } /** * Gets the current size of the internal character array buffer. * * @return The capacity */ public int capacity() { return buffer.length; } /** * Gets the character at the specified index. * * @param index the index to retrieve, must be valid * @return The character at the index * @throws IndexOutOfBoundsException if the index is invalid * @see #setCharAt(int, char) * @see #deleteCharAt(int) */ @Override public char charAt(final int index) { if (index < 0 || index >= length()) { throw new StringIndexOutOfBoundsException(index); } return buffer[index]; } /** * Clears the string builder (convenience Collections API style method). ** This method does not reduce the size of the internal character buffer. To do that, call {@code clear()} followed by {@link #minimizeCapacity()}. *
** This method is the same as {@link #setLength(int)} called with zero and is provided to match the API of Collections. *
* * @return {@code this} instance. */ public StrBuilder clear() { size = 0; return this; } /** * Checks if the string builder contains the specified char. * * @param ch the character to find. * @return true if the builder contains the character. */ public boolean contains(final char ch) { final char[] thisBuf = buffer; for (int i = 0; i < this.size; i++) { if (thisBuf[i] == ch) { return true; } } return false; } /** * Tests if the string builder contains the specified string. * * @param str the string to find. * @return true if the builder contains the string. */ public boolean contains(final String str) { return indexOf(str, 0) >= 0; } /** * Tests if the string builder contains a string matched using the specified matcher. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to search for the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return true if the matcher finds a match in the builder. */ public boolean contains(final StrMatcher matcher) { return indexOf(matcher, 0) >= 0; } /** * Deletes the characters between the two specified indices. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder delete(final int startIndex, int endIndex) { endIndex = validateRange(startIndex, endIndex); final int len = endIndex - startIndex; if (len > 0) { deleteImpl(startIndex, endIndex, len); } return this; } /** * Deletes the character wherever it occurs in the builder. * * @param ch the character to delete. * @return {@code this} instance. */ public StrBuilder deleteAll(final char ch) { for (int i = 0; i < size; i++) { if (buffer[i] == ch) { final int start = i; while (++i < size) { if (buffer[i] != ch) { break; } } final int len = i - start; deleteImpl(start, i, len); i -= len; } } return this; } /** * Deletes the string wherever it occurs in the builder. * * @param str the string to delete, null causes no action. * @return {@code this} instance. */ public StrBuilder deleteAll(final String str) { final int len = str == null ? 0 : str.length(); if (len > 0) { int index = indexOf(str, 0); while (index >= 0) { deleteImpl(index, index + len, len); index = indexOf(str, index); } } return this; } /** * Deletes all parts of the builder that the matcher matches. ** Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all occurrences where the character 'a' is * followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @return {@code this} instance. */ public StrBuilder deleteAll(final StrMatcher matcher) { return replace(matcher, null, 0, size, -1); } /** * Deletes the character at the specified index. * * @param index the index to delete. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. * @see #charAt(int) * @see #setCharAt(int, char) */ public StrBuilder deleteCharAt(final int index) { if (index < 0 || index >= size) { throw new StringIndexOutOfBoundsException(index); } deleteImpl(index, index + 1, 1); return this; } /** * Deletes the character wherever it occurs in the builder. * * @param ch the character to delete. * @return {@code this} instance. */ public StrBuilder deleteFirst(final char ch) { for (int i = 0; i < size; i++) { if (buffer[i] == ch) { deleteImpl(i, i + 1, 1); break; } } return this; } /** * Deletes the string wherever it occurs in the builder. * * @param str the string to delete, null causes no action. * @return {@code this} instance. */ public StrBuilder deleteFirst(final String str) { final int len = str == null ? 0 : str.length(); if (len > 0) { final int index = indexOf(str, 0); if (index >= 0) { deleteImpl(index, index + len, len); } } return this; } /** * Deletes the first match within the builder using the specified matcher. ** Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where the character 'a' is followed by a * number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @return {@code this} instance. */ public StrBuilder deleteFirst(final StrMatcher matcher) { return replace(matcher, null, 0, size, 1); } /** * Internal method to delete a range without validation. * * @param startIndex the start index, must be valid. * @param endIndex the end index (exclusive), must be valid. * @param len the length, must be valid. * @throws IndexOutOfBoundsException if any index is invalid. */ private void deleteImpl(final int startIndex, final int endIndex, final int len) { System.arraycopy(buffer, endIndex, buffer, startIndex, size - endIndex); size -= len; } /** * Tests whether this builder ends with the specified string. ** Note that this method handles null input quietly, unlike String. *
* * @param str the string to search for, null returns false. * @return true if the builder ends with the string. */ public boolean endsWith(final String str) { if (str == null) { return false; } final int len = str.length(); if (len == 0) { return true; } if (len > size) { return false; } int pos = size - len; for (int i = 0; i < len; i++, pos++) { if (buffer[pos] != str.charAt(i)) { return false; } } return true; } /** * Tests the capacity and ensures that it is at least the size specified. * * @param capacity the capacity to ensure. * @return {@code this} instance. */ public StrBuilder ensureCapacity(final int capacity) { if (capacity > buffer.length) { final char[] old = buffer; buffer = new char[capacity * 2]; System.arraycopy(old, 0, buffer, 0, size); } return this; } /** * Tests the contents of this builder against another to see if they contain the same character content. * * @param obj the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ @Override public boolean equals(final Object obj) { return obj instanceof StrBuilder && equals((StrBuilder) obj); } /** * Tests the contents of this builder against another to see if they contain the same character content. * * @param other the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ public boolean equals(final StrBuilder other) { if (this == other) { return true; } if (other == null) { return false; } if (this.size != other.size) { return false; } final char[] thisBuf = this.buffer; final char[] otherBuf = other.buffer; for (int i = size - 1; i >= 0; i--) { if (thisBuf[i] != otherBuf[i]) { return false; } } return true; } /** * Tests the contents of this builder against another to see if they contain the same character content ignoring case. * * @param other the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ public boolean equalsIgnoreCase(final StrBuilder other) { if (this == other) { return true; } if (this.size != other.size) { return false; } final char[] thisBuf = this.buffer; final char[] otherBuf = other.buffer; for (int i = size - 1; i >= 0; i--) { final char c1 = thisBuf[i]; final char c2 = otherBuf[i]; if (c1 != c2 && Character.toUpperCase(c1) != Character.toUpperCase(c2)) { return false; } } return true; } /** * Converts this instance to a String. * * @return This instance as a String. * @see #toString() * @since 1.12.0 */ @Override public String get() { return toString(); } /** * 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. */ public char[] getChars(char[] destination) { final int len = length(); if (destination == null || destination.length < len) { destination = new char[len]; } System.arraycopy(buffer, 0, destination, 0, len); return destination; } /** * Copies the character array into the specified array. * * @param startIndex first index to copy, inclusive, must be valid. * @param endIndex last index, exclusive, must be valid. * @param destination the destination array, must not be null or too small. * @param destinationIndex the index to start copying in destination. * @throws NullPointerException if the array is null. * @throws IndexOutOfBoundsException if any index is invalid. */ public void getChars(final int startIndex, final int endIndex, final char[] destination, final int destinationIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex < 0 || endIndex > length()) { throw new StringIndexOutOfBoundsException(endIndex); } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException("end < start"); } System.arraycopy(buffer, startIndex, destination, destinationIndex, endIndex - startIndex); } /** * Gets the text to be appended when a {@link #appendNewLine() new line} is added. * * @return The new line text, {@code null} means use the system default from {@link System#lineSeparator()}. */ public String getNewLineText() { return newLine; } /** * Gets the text to be appended when null is added. * * @return The null text, null means no append. */ public String getNullText() { return nullText; } /** * Gets a suitable hash code for this builder. * * @return a hash code. */ @Override public int hashCode() { final char[] buf = buffer; int hash = 0; for (int i = size - 1; i >= 0; i--) { hash = 31 * hash + buf[i]; } return hash; } /** * 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. */ public int indexOf(final char ch) { return indexOf(ch, 0); } /** * Searches the string builder to find the first reference to the specified char. * * @param ch the character to find. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index of the character, or -1 if not found. */ public int indexOf(final char ch, int startIndex) { startIndex = Math.max(startIndex, 0); if (startIndex >= size) { return -1; } final char[] thisBuf = buffer; for (int i = startIndex; i < size; i++) { if (thisBuf[i] == ch) { return i; } } return -1; } /** * Searches the string builder to find the first reference to the specified string. ** 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. */ public int indexOf(final String str) { return indexOf(str, 0); } /** * Searches the string builder to find the first reference to the specified string starting searching from the given index. ** Note that a null input string will return -1, whereas the JDK throws an exception. *
* * @param str the string to find, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index of the string, or -1 if not found. */ public int indexOf(final String str, int startIndex) { startIndex = Math.max(0, startIndex); if (str == null || startIndex >= size) { return StringUtils.INDEX_NOT_FOUND; } final int strLen = str.length(); if (strLen == 1) { return indexOf(str.charAt(0), startIndex); } if (strLen == 0) { return startIndex; } if (strLen > size) { return StringUtils.INDEX_NOT_FOUND; } final char[] thisBuf = buffer; final int searchLen = size - strLen + 1; for (int i = startIndex; i < searchLen; i++) { boolean found = true; for (int j = 0; j < strLen && found; j++) { found = str.charAt(j) == thisBuf[i + j]; } if (found) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder using the matcher to find the first match. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return The first index matched, or -1 if not found. */ public int indexOf(final StrMatcher matcher) { return indexOf(matcher, 0); } /** * Searches the string builder using the matcher to find the first match searching from the given index. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index matched, or -1 if not found. */ public int indexOf(final StrMatcher matcher, int startIndex) { startIndex = Math.max(startIndex, 0); if (matcher == null || startIndex >= size) { return -1; } final int len = size; final char[] buf = buffer; for (int i = startIndex; i < len; i++) { if (matcher.isMatch(buf, i, startIndex, len) > 0) { return i; } } return -1; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(int index, final boolean value) { validateIndex(index); if (value) { ensureCapacity(size + 4); System.arraycopy(buffer, index, buffer, index + 4, size - index); buffer[index++] = 't'; buffer[index++] = 'r'; buffer[index++] = 'u'; buffer[index] = 'e'; size += 4; } else { ensureCapacity(size + 5); System.arraycopy(buffer, index, buffer, index + 5, size - index); buffer[index++] = 'f'; buffer[index++] = 'a'; buffer[index++] = 'l'; buffer[index++] = 's'; buffer[index] = 'e'; size += 5; } return this; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final char value) { validateIndex(index); ensureCapacity(size + 1); System.arraycopy(buffer, index, buffer, index + 1, size - index); buffer[index] = value; size++; return this; } /** * Inserts the character array into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param chars the char array to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final char[] chars) { validateIndex(index); if (chars == null) { return insert(index, nullText); } final int len = chars.length; if (len > 0) { ensureCapacity(size + len); System.arraycopy(buffer, index, buffer, index + len, size - index); System.arraycopy(chars, 0, buffer, index, len); size += len; } return this; } /** * Inserts part of the character array into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param chars the char array to insert. * @param offset the offset into the character array to start at, must be valid. * @param length the length of the character array part to copy, must be positive. * @return {@code this} instance. * @throws IndexOutOfBoundsException if any index is invalid. */ public StrBuilder insert(final int index, final char[] chars, final int offset, final int length) { validateIndex(index); if (chars == null) { return insert(index, nullText); } if (offset < 0 || offset > chars.length) { throw new StringIndexOutOfBoundsException("Invalid offset: " + offset); } if (length < 0 || offset + length > chars.length) { throw new StringIndexOutOfBoundsException("Invalid length: " + length); } if (length > 0) { ensureCapacity(size + length); System.arraycopy(buffer, index, buffer, index + length, size - index); System.arraycopy(chars, offset, buffer, index, length); size += length; } return this; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final double value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final float value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final int value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final long value) { return insert(index, String.valueOf(value)); } /** * Inserts the string representation of an object into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param obj the object to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, final Object obj) { if (obj == null) { return insert(index, nullText); } return insert(index, obj.toString()); } /** * Inserts the string into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param str the string to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder insert(final int index, String str) { validateIndex(index); if (str == null) { str = nullText; } if (str != null) { final int strLen = str.length(); if (strLen > 0) { final int newSize = size + strLen; ensureCapacity(newSize); System.arraycopy(buffer, index, buffer, index + strLen, size - index); size = newSize; str.getChars(0, strLen, buffer, index); } } return this; } /** * Tests if the string builder is empty (convenience Collections API style method). ** This method is the same as checking {@link #length()} and is provided to match the API of Collections. *
* * @return {@code true} if the size is {@code 0}. */ public boolean isEmpty() { return size == 0; } /** * Tests if the string builder is not empty (convenience Collections API style method). ** This method is the same as checking {@link #length()} and is provided to match the API of Collections. *
* * @return {@code true} if the size is greater than {@code 0}. * @since 1.10.0 */ public boolean isNotEmpty() { return size > 0; } /** * 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. */ public int lastIndexOf(final char ch) { return lastIndexOf(ch, size - 1); } /** * Searches the string builder to find the last reference to the specified char. * * @param ch the character to find. * @param startIndex the index to start at, invalid index rounded to edge. * @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; if (startIndex < 0) { return -1; } for (int i = startIndex; i >= 0; i--) { if (buffer[i] == ch) { return i; } } return -1; } /** * Searches the string builder to find the last reference to the specified string. ** 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. */ public int lastIndexOf(final String str) { return lastIndexOf(str, size - 1); } /** * Searches the string builder to find the last reference to the specified string starting searching from the given index. ** Note that a null input string will return -1, whereas the JDK throws an exception. *
* * @param str the string to find, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The last index of the string, or -1 if not found. */ public int lastIndexOf(final String str, int startIndex) { startIndex = startIndex >= size ? size - 1 : startIndex; if (str == null || startIndex < 0) { return StringUtils.INDEX_NOT_FOUND; } final int strLen = str.length(); if (strLen == 0) { return startIndex; } if (strLen > size) { return StringUtils.INDEX_NOT_FOUND; } if (strLen == 1) { return lastIndexOf(str.charAt(0), startIndex); } for (int i = startIndex - strLen + 1; i >= 0; i--) { boolean found = true; for (int j = 0; j < strLen && found; j++) { found = str.charAt(j) == buffer[i + j]; } if (found) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder using the matcher to find the last match. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return The last index matched, or -1 if not found. */ public int lastIndexOf(final StrMatcher matcher) { return lastIndexOf(matcher, size); } /** * Searches the string builder using the matcher to find the last match searching from the given index. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The last index matched, or -1 if not found. */ public int lastIndexOf(final StrMatcher matcher, int startIndex) { startIndex = startIndex >= size ? size - 1 : startIndex; if (matcher == null || startIndex < 0) { return -1; } final char[] buf = buffer; final int endIndex = startIndex + 1; for (int i = startIndex; i >= 0; i--) { if (matcher.isMatch(buf, i, 0, endIndex) > 0) { return i; } } return -1; } /** * Extracts the leftmost characters from the string builder without throwing an exception. ** This method extracts the left {@code length} characters from the builder. If this many characters are not available, the whole builder is returned. Thus * the returned string may be shorter than the length requested. *
* * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String leftString(final int length) { if (length <= 0) { return StringUtils.EMPTY; } if (length >= size) { return new String(buffer, 0, size); } return new String(buffer, 0, length); } /** * Gets the length of the string builder. * * @return The length */ @Override public int length() { return size; } /** * Extracts some characters from the middle of the string builder without throwing an exception. ** This method extracts {@code length} characters from the builder at the specified index. If the index is negative it is treated as zero. If the index is * greater than the builder size, it is treated as the builder size. If the length is negative, the empty string is returned. If insufficient characters are * available in the builder, as much as possible is returned. Thus the returned string may be shorter than the length requested. *
* * @param index the index to start at, negative means zero. * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String midString(int index, final int length) { if (index < 0) { index = 0; } if (length <= 0 || index >= size) { return StringUtils.EMPTY; } if (size <= index + length) { return new String(buffer, index, size - index); } return new String(buffer, index, length); } /** * Minimizes the capacity to the actual length of the string. * * @return {@code this} instance. */ public StrBuilder minimizeCapacity() { if (buffer.length > length()) { final char[] old = buffer; buffer = new char[length()]; System.arraycopy(old, 0, buffer, 0, size); } return this; } /** * If possible, reads chars from the provided {@link Readable} directly into underlying character buffer without making extra copies. * * @param readable object to read from. * @return The number of characters read. * @throws IOException if an I/O error occurs. * @see #appendTo(Appendable) */ public int readFrom(final Readable readable) throws IOException { final int oldSize = size; if (readable instanceof Reader) { final Reader r = (Reader) readable; ensureCapacity(size + 1); int read; while ((read = r.read(buffer, size, buffer.length - size)) != -1) { size += read; ensureCapacity(size + 1); } } else if (readable instanceof CharBuffer) { final CharBuffer cb = (CharBuffer) readable; final int remaining = cb.remaining(); ensureCapacity(size + remaining); cb.get(buffer, size, remaining); size += remaining; } else { while (true) { ensureCapacity(size + 1); final CharBuffer buf = CharBuffer.wrap(buffer, size, buffer.length - size); final int read = readable.read(buf); if (read == -1) { break; } size += read; } } return size - oldSize; } /** * Replaces a portion of the string builder with another string. The length of the inserted string does not have to match the removed length. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @param replaceStr the string to replace with, null means delete range. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public StrBuilder replace(final int startIndex, int endIndex, final String replaceStr) { endIndex = validateRange(startIndex, endIndex); final int insertLen = replaceStr == null ? 0 : replaceStr.length(); replaceImpl(startIndex, endIndex, endIndex - startIndex, replaceStr, insertLen); return this; } /** * Advanced search and replaces within the builder using a matcher. ** Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by * a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the string to replace the match with, null is a delete. * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @param replaceCount the number of times to replace, -1 for replace all. * @return {@code this} instance. * @throws IndexOutOfBoundsException if start index is invalid. */ public StrBuilder replace(final StrMatcher matcher, final String replaceStr, final int startIndex, int endIndex, final int replaceCount) { endIndex = validateRange(startIndex, endIndex); return replaceImpl(matcher, replaceStr, startIndex, endIndex, replaceCount); } /** * Replaces the search character with the replace character throughout the builder. * * @param search the search character. * @param replace the replace character. * @return {@code this} instance. */ public StrBuilder replaceAll(final char search, final char replace) { if (search != replace) { for (int i = 0; i < size; i++) { if (buffer[i] == search) { buffer[i] = replace; } } } return this; } /** * Replaces the search string with the replace string throughout the builder. * * @param searchStr the search string, null causes no action to occur. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public StrBuilder replaceAll(final String searchStr, final String replaceStr) { final int searchLen = searchStr == null ? 0 : searchStr.length(); if (searchLen > 0) { final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); int index = indexOf(searchStr, 0); while (index >= 0) { replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen); index = indexOf(searchStr, index + replaceLen); } } return this; } /** * Replaces all matches within the builder with the replace string. ** Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace all occurrences where the character 'a' is * followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public StrBuilder replaceAll(final StrMatcher matcher, final String replaceStr) { return replace(matcher, replaceStr, 0, size, -1); } /** * Replaces the first instance of the search character with the replace character in the builder. * * @param search the search character. * @param replace the replace character. * @return {@code this} instance. */ public StrBuilder replaceFirst(final char search, final char replace) { if (search != replace) { for (int i = 0; i < size; i++) { if (buffer[i] == search) { buffer[i] = replace; break; } } } return this; } /** * Replaces the first instance of the search string with the replace string. * * @param searchStr the search string, null causes no action to occur. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public StrBuilder replaceFirst(final String searchStr, final String replaceStr) { final int searchLen = searchStr == null ? 0 : searchStr.length(); if (searchLen > 0) { final int index = indexOf(searchStr, 0); if (index >= 0) { final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen); } } return this; } /** * Replaces the first match within the builder with the replace string. ** Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where the character 'a' is followed by a * number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public StrBuilder replaceFirst(final StrMatcher matcher, final String replaceStr) { return replace(matcher, replaceStr, 0, size, 1); } /** * Internal method to delete a range without validation. * * @param startIndex the start index, must be valid. * @param endIndex the end index (exclusive), must be valid. * @param removeLen the length to remove (endIndex - startIndex), must be valid. * @param insertStr the string to replace with, null means delete range. * @param insertLen the length of the insert string, must be valid. * @throws IndexOutOfBoundsException if any index is invalid. */ private void replaceImpl(final int startIndex, final int endIndex, final int removeLen, final String insertStr, final int insertLen) { final int newSize = size - removeLen + insertLen; if (insertLen != removeLen) { ensureCapacity(newSize); System.arraycopy(buffer, endIndex, buffer, startIndex + insertLen, size - endIndex); size = newSize; } if (insertLen > 0) { insertStr.getChars(0, insertLen, buffer, startIndex); } } /** * Replaces within the builder using a matcher. ** Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by * a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the string to replace the match with, null is a delete. * @param from the start index, must be valid. * @param to the end index (exclusive), must be valid. * @param replaceCount the number of times to replace, -1 for replace all. * @return {@code this} instance. * @throws IndexOutOfBoundsException if any index is invalid. */ private StrBuilder replaceImpl(final StrMatcher matcher, final String replaceStr, final int from, int to, int replaceCount) { if (matcher == null || size == 0) { return this; } final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); for (int i = from; i < to && replaceCount != 0; i++) { final char[] buf = buffer; final int removeLen = matcher.isMatch(buf, i, from, to); if (removeLen > 0) { replaceImpl(i, i + removeLen, removeLen, replaceStr, replaceLen); to = to - removeLen + replaceLen; i = i + replaceLen - 1; if (replaceCount > 0) { replaceCount--; } } } return this; } /** * Reverses the string builder placing each character in the opposite index. * * @return {@code this} instance. */ public StrBuilder reverse() { if (size == 0) { return this; } final int half = size / 2; final char[] buf = buffer; for (int leftIdx = 0, rightIdx = size - 1; leftIdx < half; leftIdx++, rightIdx--) { final char swap = buf[leftIdx]; buf[leftIdx] = buf[rightIdx]; buf[rightIdx] = swap; } return this; } /** * Extracts the rightmost characters from the string builder without throwing an exception. ** This method extracts the right {@code length} characters from the builder. If this many characters are not available, the whole builder is returned. Thus * the returned string may be shorter than the length requested. *
* * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String rightString(final int length) { if (length <= 0) { return StringUtils.EMPTY; } if (length >= size) { return new String(buffer, 0, size); } return new String(buffer, size - length, length); } /** * Sets the character at the specified index. * * @param index the index to set. * @param ch the new character. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. * @see #charAt(int) * @see #deleteCharAt(int) */ public StrBuilder setCharAt(final int index, final char ch) { if (index < 0 || index >= length()) { throw new StringIndexOutOfBoundsException(index); } buffer[index] = ch; return this; } /** * Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero. * * @param length the length to set to, must be zero or positive. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the length is negative. */ public StrBuilder setLength(final int length) { if (length < 0) { throw new StringIndexOutOfBoundsException(length); } if (length < size) { size = length; } else if (length > size) { ensureCapacity(length); Arrays.fill(buffer, size, length, CharUtils.NUL); size = length; } return this; } /** * Sets the text to be appended when {@link #appendNewLine() new line} is called. * * @param newLine the new line text, {@code null} means use the system default from {@link System#lineSeparator()}. * @return {@code this} instance. */ public StrBuilder setNewLineText(final String newLine) { this.newLine = newLine; return this; } /** * Sets the text to be appended when null is added. * * @param nullText the null text, null means no append. * @return {@code this} instance. */ public StrBuilder setNullText(String nullText) { if (nullText != null && nullText.isEmpty()) { nullText = null; } this.nullText = nullText; return this; } /** * Gets the length of the string builder. ** This method is the same as {@link #length()} and is provided to match the API of Collections. *
* * @return The length. */ public int size() { return size; } /** * Checks whether this builder starts with the specified string. ** Note that this method handles null input quietly, unlike String. *
* * @param str the string to search for, null returns false. * @return true if the builder starts with the string. */ public boolean startsWith(final String str) { if (str == null) { return false; } final int len = str.length(); if (len == 0) { return true; } if (len > size) { return false; } for (int i = 0; i < len; i++) { if (buffer[i] != str.charAt(i)) { return false; } } return true; } /** * {@inheritDoc} */ @Override public CharSequence subSequence(final int startIndex, final int endIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex > size) { throw new StringIndexOutOfBoundsException(endIndex); } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException(endIndex - startIndex); } return substring(startIndex, endIndex); } /** * Extracts a portion of this string builder as a string. * * @param start the start index, inclusive, must be valid. * @return The new string. * @throws IndexOutOfBoundsException if the index is invalid. */ public String substring(final int start) { return substring(start, size); } /** * Extracts a portion of this string builder as a string. ** Note: This method treats an endIndex greater than the length of the builder as equal to the length of the builder, and continues without error, unlike * StringBuffer or String. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return The new string. * @throws IndexOutOfBoundsException if the index is invalid. */ public String substring(final int startIndex, int endIndex) { endIndex = validateRange(startIndex, endIndex); return new String(buffer, startIndex, endIndex - startIndex); } /** * Copies the builder's character array into a new character array. * * @return a new array that represents the contents of the builder. */ public char[] toCharArray() { return size == 0 ? ArrayUtils.EMPTY_CHAR_ARRAY : Arrays.copyOf(buffer, size); } /** * Copies part of the builder's character array into a new character array. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return a new array that holds part of the contents of the builder. * @throws IndexOutOfBoundsException if startIndex is invalid, or if endIndex is invalid (but endIndex greater than size is valid). */ public char[] toCharArray(final int startIndex, int endIndex) { endIndex = validateRange(startIndex, endIndex); final int len = endIndex - startIndex; if (len == 0) { return ArrayUtils.EMPTY_CHAR_ARRAY; } final char[] chars = new char[len]; System.arraycopy(buffer, startIndex, chars, 0, len); return chars; } /** * Gets a String version of the string builder, creating a new instance each time the method is called. *
* Note that unlike StringBuffer, the string version returned is independent of the string builder. *
* * @return The builder as a String. */ @Override public String toString() { return new String(buffer, 0, size); } /** * Gets a StringBuffer version of the string builder, creating a new instance each time the method is called. * * @return The builder as a StringBuffer. */ public StringBuffer toStringBuffer() { return new StringBuffer(size).append(buffer, 0, size); } /** * Gets a StringBuilder version of the string builder, creating a new instance each time the method is called. * * @return The builder as a StringBuilder. */ public StringBuilder toStringBuilder() { return new StringBuilder(size).append(buffer, 0, size); } /** * Trims the builder by removing characters less than or equal to a space from the beginning and end. * * @return {@code this} instance. */ public StrBuilder trim() { if (size == 0) { return this; } int len = size; final char[] buf = buffer; int pos = 0; while (pos < len && buf[pos] <= ' ') { pos++; } while (pos < len && buf[len - 1] <= ' ') { len--; } if (len < size) { delete(len, size); } if (pos > 0) { delete(0, pos); } return this; } /** * Validates parameters defining a single index in the builder. * * @param index the index, must be valid. * @throws IndexOutOfBoundsException if the index is invalid. */ protected void validateIndex(final int index) { if (index < 0 || index > size) { throw new StringIndexOutOfBoundsException(index); } } /** * Validates parameters defining a range of the builder. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return The new string. * @throws IndexOutOfBoundsException if the index is invalid. */ protected int validateRange(final int startIndex, int endIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex > size) { endIndex = size; } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException("end < start"); } return endIndex; } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/StrLookup.java 0000664 0000000 0000000 00000016071 15114327406 0031366 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.util.Collections; import java.util.Map; import java.util.Objects; import java.util.ResourceBundle; import org.apache.commons.text.lookup.StringLookup; import org.apache.commons.text.lookup.StringLookupFactory; /** * Lookup a String key to a String value. ** This class represents the simplest form of a string to string map. It has a benefit over a map in that it can create * the result on demand based on the key. *
** This class comes complete with various factory methods. If these do not suffice, you can subclass and implement your * own matcher. *
** For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the value * on demand from the database *
* * @param* 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 */ @Override public String lookup(final String key) { return Objects.toString(map.get(key), null); } @Override public String toString() { return super.toString() + " [map=" + map + "]"; } } /** * Lookup implementation based on a ResourceBundle. */ private static final class ResourceBundleLookup extends StrLookup* If the map is null, then null will be returned from every lookup. The map result object is converted to a string * using toString(). *
* * @param* If the ResourceBundle is null, then null will be returned from every lookup. The map result object is converted * to a string using toString(). *
* * @param resourceBundle the map of keys to values, may be null. * @return a lookup using the map, not null. * @see StringLookupFactory#resourceBundleStringLookup(String) */ public static StrLookup* If a security manager blocked access to system properties, then null will be returned from every lookup. *
** If a null key is used, this lookup will throw a NullPointerException. *
* * @return a lookup using system properties, not null. */ public static StrLookup* This class comes complete with various factory methods. * If these do not suffice, you can subclass and implement your own matcher. *
* * @since 1.0 * @deprecated Deprecated as of 1.3, use {@link StringMatcherFactory} instead. This class will be removed in 2.0. */ @Deprecated public abstract class StrMatcher { /** * Class used to define a character for matching purposes. */ private static final class CharMatcher extends StrMatcher { /** The character to match. */ private final char ch; /** * Constructor that creates a matcher that matches a single character. * * @param ch the character to match. */ private CharMatcher(final char ch) { this.ch = ch; } /** * Returns {@code 1} if there is a match, or {@code 0} if there is no match. * * @param buffer the text content to match against, do not change. * @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. */ @Override public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) { return ch == buffer[pos] ? 1 : 0; } } /** * Class used to define a set of characters for matching purposes. */ private static final class CharSetMatcher extends StrMatcher { /** The set of characters to match. */ private final char[] chars; /** * Constructor that creates a matcher from a character array. * * @param chars the characters to match, must not be null */ private CharSetMatcher(final char[] chars) { this.chars = chars.clone(); Arrays.sort(this.chars); } /** * Returns {@code 1} if there is a match, or {@code 0} if there is no match. * * @param buffer the text content to match against, do not change. * @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. */ @Override public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) { return Arrays.binarySearch(chars, buffer[pos]) >= 0 ? 1 : 0; } } /** * Class used to match no characters. */ private static final class NoMatcher extends StrMatcher { /** * Constructs a new instance of {@code NoMatcher}. */ private NoMatcher() { } /** * Always returns {@code 0}. * * @param buffer the text content to match against, do not change. * @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. */ @Override public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) { return 0; } } /** * Class used to define a set of characters for matching purposes. */ private static final class StringMatcher extends StrMatcher { /** The string to match, as a character array. */ private final char[] chars; /** * Constructor that creates a matcher from a String. * * @param str the string to match, must not be null */ private StringMatcher(final String str) { chars = str.toCharArray(); } /** * Returns the number of matching characters, or zero if there is no match. * * @param buffer the text content to match against, do not change. * @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. */ @Override public int isMatch(final char[] buffer, int pos, final int bufferStart, final int bufferEnd) { final int len = chars.length; if (pos + len > bufferEnd) { return 0; } for (int i = 0; i < chars.length; i++, pos++) { if (chars[i] != buffer[pos]) { return 0; } } return len; } @Override public String toString() { return super.toString() + ' ' + Arrays.toString(chars); } } /** * Class used to match whitespace as per trim(). */ private static final class TrimMatcher extends StrMatcher { /** * Constructs a new instance of {@code TrimMatcher}. */ private TrimMatcher() { } /** * Returns whether or not the given character matches. * * @param buffer the text content to match against, do not change. * @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. */ @Override public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) { return buffer[pos] <= 32 ? 1 : 0; } } /** * Matches the comma character. */ private static final StrMatcher COMMA_MATCHER = new CharMatcher(','); /** * Matches the tab character. */ private static final StrMatcher TAB_MATCHER = new CharMatcher('\t'); /** * Matches the space character. */ private static final StrMatcher SPACE_MATCHER = new CharMatcher(' '); /** * Matches the same characters as StringTokenizer, * namely space, tab, newline, form feed. */ private static final StrMatcher SPLIT_MATCHER = new CharSetMatcher(" \t\n\r\f".toCharArray()); /** * Matches the String trim() whitespace characters. */ private static final StrMatcher TRIM_MATCHER = new TrimMatcher(); /** * Matches the double quote character. */ private static final StrMatcher SINGLE_QUOTE_MATCHER = new CharMatcher('\''); /** * Matches the double quote character. */ private static final StrMatcher DOUBLE_QUOTE_MATCHER = new CharMatcher('"'); /** * Matches the single or double quote character. */ private static final StrMatcher QUOTE_MATCHER = new CharSetMatcher("'\"".toCharArray()); /** * Matches no characters. */ private static final StrMatcher NONE_MATCHER = new NoMatcher(); /** * Creates a matcher from a character. * * @param ch the character to match, must not be null. * @return a new Matcher for the given char. */ public static StrMatcher charMatcher(final char ch) { return new CharMatcher(ch); } /** * Creates a matcher from a set of characters. * * @param chars the characters to match, null or empty matches nothing. * @return a new matcher for the given char[]. */ public static StrMatcher charSetMatcher(final char... chars) { if (ArrayUtils.isEmpty(chars)) { return NONE_MATCHER; } if (chars.length == 1) { return new CharMatcher(chars[0]); } return new CharSetMatcher(chars); } /** * Creates a matcher from a string representing a set of characters. * * @param chars the characters to match, null or empty matches nothing. * @return a new Matcher for the given characters. */ public static StrMatcher charSetMatcher(final String chars) { if (chars == null || chars.isEmpty()) { return NONE_MATCHER; } if (chars.length() == 1) { return new CharMatcher(chars.charAt(0)); } return new CharSetMatcher(chars.toCharArray()); } /** * Returns a matcher which matches the comma character. * * @return a matcher for a comma. */ public static StrMatcher commaMatcher() { return COMMA_MATCHER; } /** * Returns a matcher which matches the double quote character. * * @return a matcher for a double quote. */ public static StrMatcher doubleQuoteMatcher() { return DOUBLE_QUOTE_MATCHER; } /** * Matches no characters. * * @return a matcher that matches nothing. */ public static StrMatcher noneMatcher() { return NONE_MATCHER; } /** * Returns a matcher which matches the single or double quote character. * * @return a matcher for a single or double quote. */ public static StrMatcher quoteMatcher() { return QUOTE_MATCHER; } /** * Returns a matcher which matches the single quote character. * * @return a matcher for a single quote. */ public static StrMatcher singleQuoteMatcher() { return SINGLE_QUOTE_MATCHER; } /** * Returns a matcher which matches the space character. * * @return a matcher for a space. */ public static StrMatcher spaceMatcher() { return SPACE_MATCHER; } /** * Matches the same characters as StringTokenizer, * namely space, tab, newline and form feed. * * @return The split matcher. */ public static StrMatcher splitMatcher() { return SPLIT_MATCHER; } /** * Creates a matcher from a string. * * @param str the string to match, null or empty matches nothing * @return a new Matcher for the given String */ public static StrMatcher stringMatcher(final String str) { if (str == null || str.isEmpty()) { return NONE_MATCHER; } return new StringMatcher(str); } /** * Returns a matcher which matches the tab character. * * @return a matcher for a tab. */ public static StrMatcher tabMatcher() { return TAB_MATCHER; } /** * Matches the String trim() whitespace characters. * * @return The trim matcher. */ public static StrMatcher trimMatcher() { return TRIM_MATCHER; } /** * Constructs a new instance. */ protected StrMatcher() { } /** * Returns the number of matching characters, or zero if there is no match. ** This method is called to check for a match. * The parameter {@code pos} represents the current position to be * checked in the string {@code buffer} (a character array which must * not be changed). * The API guarantees that {@code pos} is a valid index for {@code buffer}. *
** The matching code may check one character or many. * It may check characters preceding {@code pos} as well as those after. *
** It must return zero for no match, or a positive number if a match was found. * The number indicates the number of characters that matched. *
* * @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. */ public int isMatch(final char[] buffer, final int pos) { return isMatch(buffer, pos, 0, buffer.length); } /** * Returns the number of matching characters, or zero if there is no match. ** This method is called to check for a match. * The parameter {@code pos} represents the current position to be * checked in the string {@code buffer} (a character array which must * not be changed). * The API guarantees that {@code pos} is a valid index for {@code buffer}. *
** The character array may be larger than the active area to be matched. * Only values in the buffer between the specified indices may be accessed. *
** The matching code may check one character or many. * It may check characters preceding {@code pos} as well as those * after, so long as no checks exceed the bounds specified. *
** It must return zero for no match, or a positive number if a match was found. * The number indicates the number of characters that matched. *
* * @param buffer the text content to match against, do not change. * @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. */ public abstract int isMatch(char[] buffer, int pos, int bufferStart, int bufferEnd); } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/StrSubstitutor.java 0000664 0000000 0000000 00000144555 15114327406 0032475 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.util.ArrayList; import java.util.List; import java.util.Map; import java.util.Properties; import java.util.function.Function; import java.util.stream.Collectors; import org.apache.commons.lang3.Validate; /** * Substitutes variables within a string by values. ** This class takes a piece of text and substitutes all the variables within it. * The default definition of a variable is {@code ${variableName}}. * The prefix and suffix can be changed via constructors and set methods. *
* Variable values are typically resolved from a map, but could also be resolved * from system properties, or by supplying a custom variable resolver. *
* The simplest example is to use this class to replace Java System properties. For example: *
* StrSubstitutor.replaceSystemProperties(
* "You are running with java.version = ${java.version} and os.name = ${os.name}.");
*
* * Typical usage of this class follows the following pattern: First an instance is created * and initialized with the map that contains the values for the available variables. * If a prefix and/or suffix for variables should be used other than the default ones, * the appropriate settings can be performed. After that the {@code replace()} * method can be called passing in the source text for interpolation. In the returned * text all variable references (as long as their values are known) will be resolved. * The following example demonstrates this: *
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("animal", "quick brown fox");
* valuesMap.put("target", "lazy dog");
* String templateString = "The ${animal} jumped over the ${target}.";
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
*
* yielding:
* * The quick brown fox jumped over the lazy dog. **
* Also, this class allows to set a default value for unresolved variables. * The default value for a variable can be appended to the variable name after the variable * default value delimiter. The default value of the variable default value delimiter is ':-', * as in bash and other *nix shells, as those are arguably where the default ${} delimiter set originated. * The variable default value delimiter can be manually set by calling {@link #setValueDelimiterMatcher(StrMatcher)}, * {@link #setValueDelimiter(char)} or {@link #setValueDelimiter(String)}. * The following shows an example with variable default value settings: *
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("animal", "quick brown fox");
* valuesMap.put("target", "lazy dog");
* String templateString = "The ${animal} jumped over the ${target}. ${undefined.number:-1234567890}.";
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
*
* yielding:
* * The quick brown fox jumped over the lazy dog. 1234567890. **
* In addition to this usage pattern there are some static convenience methods that * cover the most common use cases. These methods can be used without the need of * manually creating an instance. However if multiple replace operations are to be * performed, creating and reusing an instance of this class will be more efficient. *
* Variable replacement works in a recursive way. Thus, if a variable value contains * a variable then that variable will also be replaced. Cyclic replacements are * detected and will cause an exception to be thrown. *
* Sometimes the interpolation's result must contain a variable prefix. As an example * take the following source text: *
* The variable ${${name}} must be used.
*
* Here only the variable's name referred to in the text should be replaced resulting
* in the text (assuming that the value of the {@code name} variable is {@code x}):
*
* The variable ${x} must be used.
*
* To achieve this effect there are two possibilities: Either set a different prefix
* and suffix for variables which do not conflict with the result text you want to
* produce. The other possibility is to use the escape character, by default '$'.
* If this character is placed before a variable reference, this reference is ignored
* and won't be replaced. For example:
*
* The variable $${${name}} must be used.
*
* * In some complex scenarios you might even want to perform substitution in the * names of variables, for instance *
* ${jre-${java.specification.version}}
*
* {@code StrSubstitutor} supports this recursive substitution in variable
* names, but it has to be enabled explicitly by setting the
* {@link #setEnableSubstitutionInVariables(boolean) enableSubstitutionInVariables}
* property to true.
* This class is not thread safe.
* * @since 1.0 * @deprecated Deprecated as of 1.3, use {@link StringSubstitutor} instead. This class will be removed in 2.0. */ @Deprecated public class StrSubstitutor { /** * Constant for the default escape character. */ public static final char DEFAULT_ESCAPE = '$'; /** * Constant for the default variable prefix. */ public static final StrMatcher DEFAULT_PREFIX = StrMatcher.stringMatcher("${"); /** * Constant for the default variable suffix. */ public static final StrMatcher DEFAULT_SUFFIX = StrMatcher.stringMatcher("}"); /** * Constant for the default value delimiter of a variable. */ public static final StrMatcher DEFAULT_VALUE_DELIMITER = StrMatcher.stringMatcher(":-"); /** * Replaces all the occurrences of variables in the given source object with * their matching values from the map. * * @param* The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This delimiter is * expressed in terms of a matcher allowing advanced variable default value delimiter matches. *
** If it returns null, then the variable default value resolution is disabled. *
* * @return The variable default value delimiter matcher in use, may be null. */ public StrMatcher getValueDelimiterMatcher() { return valueDelimiterMatcher; } /** * Gets the variable prefix matcher currently in use. ** 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. */ public StrMatcher getVariablePrefixMatcher() { return prefixMatcher; } /** * Gets the VariableResolver that is used to lookup variables. * * @return The VariableResolver. */ public StrLookup getVariableResolver() { return this.variableResolver; } /** * Gets the variable suffix matcher currently in use. ** 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. */ public StrMatcher getVariableSuffixMatcher() { return suffixMatcher; } /** * Returns a flag whether substitution is disabled in variable values.If set to * true, the values of variables can contain other variables will not be * processed and substituted original variable is evaluated, e.g. *
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("name", "Douglas ${surname}");
* valuesMap.put("surname", "Crockford");
* String templateString = "Hi ${name}";
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
*
* * yielding: *
*
* Hi Douglas ${surname}
*
*
* @return The substitution in variable values flag.
* @since 1.2
*/
public boolean isDisableSubstitutionInValues() {
return disableSubstitutionInValues;
}
/**
* Returns a flag whether substitution is done in variable names.
*
* @return The substitution in variable names flag.
*/
public boolean isEnableSubstitutionInVariables() {
return enableSubstitutionInVariables;
}
/**
* Returns the flag controlling whether escapes are preserved during substitution.
*
* @return The preserve escape flag.
*/
public boolean isPreserveEscapes() {
return preserveEscapes;
}
/**
* Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. 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.
*/
public String replace(final char[] source) {
if (source == null) {
return null;
}
final StrBuilder buf = new StrBuilder(source.length).append(source);
substitute(buf, 0, source.length);
return buf.toString();
}
/**
* Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not
* altered by this method.
* * Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned. *
* * @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. */ public String replace(final char[] source, final int offset, final int length) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template. 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. */ public String replace(final CharSequence source) { if (source == null) { return null; } return replace(source, 0, source.length()); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template. The source is not altered by * this method. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned. *
* * @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. */ public String replace(final CharSequence source, final int offset, final int length) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables in the given source object with their matching values from the resolver. The input source object is converted * to a string using {@code toString} and is not altered. * * @param source the source to replace in, null returns null. * @return The result of the replace operation. */ public String replace(final Object source) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder().append(source); substitute(buf, 0, buf.length()); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. 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. */ public String replace(final StrBuilder source) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(source.length()).append(source); substitute(buf, 0, buf.length()); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. The builder is not * altered by this method. ** Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not returned. *
* * @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. */ public String replace(final StrBuilder source, final int offset, final int length) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values 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. */ public String replace(final String source) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(source); if (!substitute(buf, 0, source.length())) { return source; } return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template. ** Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned. *
* * @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. */ public String replace(final String source, final int offset, final int length) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return source.substring(offset, offset + length); } return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. 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. */ public String replace(final StringBuffer source) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(source.length()).append(source); substitute(buf, 0, buf.length()); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not * altered by this method. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned. *
* * @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. */ public String replace(final StringBuffer source, final int offset, final int length) { if (source == null) { return null; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the resolver. * * @param source the builder to replace in, updated, null returns zero. * @return true if altered. */ public boolean replaceIn(final StrBuilder source) { if (source == null) { return false; } return substitute(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the resolver. ** Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is not deleted. *
* * @param source the builder to replace in, null returns zero. * @param offset the start offset within the array, must be valid. * @param length the length within the builder to be processed, must be valid. * @return true if altered. */ public boolean replaceIn(final StrBuilder source, final int offset, final int length) { if (source == null) { return false; } return substitute(source, offset, length); } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the * result. * * @param source the buffer to replace in, updated, null returns zero. * @return true if altered. */ public boolean replaceIn(final StringBuffer source) { if (source == null) { return false; } return replaceIn(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the * result. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted. *
* * @param source the buffer to replace in, updated, null returns zero. * @param offset the start offset within the array, must be valid. * @param length the length within the buffer to be processed, must be valid. * @return true if altered. */ public boolean replaceIn(final StringBuffer source, final int offset, final int length) { if (source == null) { return false; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return false; } source.replace(offset, offset + length, buf.toString()); return true; } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the * result. * * @param source the buffer to replace in, updated, null returns zero. * @return true if altered. */ public boolean replaceIn(final StringBuilder source) { if (source == null) { return false; } return replaceIn(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the resolver. The builder is updated with the * result. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted. *
* * @param source the buffer to replace in, updated, null returns zero. * @param offset the start offset within the array, must be valid. * @param length the length within the buffer to be processed, must be valid. * @return true if altered. */ public boolean replaceIn(final StringBuilder source, final int offset, final int length) { if (source == null) { return false; } final StrBuilder buf = new StrBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return false; } source.replace(offset, offset + length, buf.toString()); return true; } /** * Internal method that resolves the value of a variable. ** Most users of this class do not need to call this method. This method is called automatically by the substitution process. *
** Writers of subclasses can override this method if they need to alter how each substitution occurs. The method is passed the variable's name and must * return the corresponding value. This implementation uses the {@link #getVariableResolver()} with the variable's name as the key. *
* * @param variableName the name of the variable, not null. * @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 null if the variable is unknown. */ protected String resolveVariable(final String variableName, final StrBuilder buf, final int startPos, final int endPos) { final StrLookup resolver = getVariableResolver(); if (resolver == null) { return null; } return resolver.apply(variableName); } /** * Sets a flag whether substitution is done in variable values (recursive). * * @param disableSubstitutionInValues true if substitution in variable value are disabled. * @since 1.2 */ public void setDisableSubstitutionInValues(final boolean disableSubstitutionInValues) { this.disableSubstitutionInValues = disableSubstitutionInValues; } /** * Sets a flag whether substitution is done in variable names. If set to true, the names of variables can contain other variables which are * processed first before the original variable is evaluated, e.g. {@code ${jre-${java.version}}}. The default value is false. * * @param enableSubstitutionInVariables the new value of the flag. */ public void setEnableSubstitutionInVariables(final boolean enableSubstitutionInVariables) { this.enableSubstitutionInVariables = enableSubstitutionInVariables; } /** * Sets the escape character. If this character is placed before a variable reference in the source text, this variable will be ignored. * * @param escapeCharacter the escape character (0 for disabling escaping) */ public void setEscapeChar(final char escapeCharacter) { this.escapeChar = escapeCharacter; } /** * Sets a flag controlling whether escapes are preserved during substitution. If set to true, the escape character is retained during * substitution (e.g. {@code $${this-is-escaped}} remains {@code $${this-is-escaped}}). If set to false, the escape character is removed * during substitution (e.g. {@code $${this-is-escaped}} becomes {@code ${this-is-escaped}}). The default value is false * * @param preserveEscapes true if escapes are to be preserved */ public void setPreserveEscapes(final boolean preserveEscapes) { this.preserveEscapes = preserveEscapes; } /** * Sets the variable default value delimiter to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This method allows a * single character variable default value delimiter to be easily set. *
* * @param valueDelimiter the variable default value delimiter character to use. * @return {@code this} instance. */ public StrSubstitutor setValueDelimiter(final char valueDelimiter) { return setValueDelimiterMatcher(StrMatcher.charMatcher(valueDelimiter)); } /** * Sets the variable default value delimiter to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This method allows a * string variable default value delimiter to be easily set. *
** If the {@code valueDelimiter} is null or empty string, then the variable default value resolution becomes disabled. *
* * @param valueDelimiter the variable default value delimiter string to use, may be null or empty * @return {@code this} instance. */ public StrSubstitutor setValueDelimiter(final String valueDelimiter) { if (valueDelimiter == null || valueDelimiter.isEmpty()) { setValueDelimiterMatcher(null); return this; } return setValueDelimiterMatcher(StrMatcher.stringMatcher(valueDelimiter)); } /** * Sets the variable default value delimiter matcher to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This delimiter is * expressed in terms of a matcher allowing advanced variable default value delimiter matches. *
** If the {@code valueDelimiterMatcher} is null, then the variable default value resolution becomes disabled. *
* * @param valueDelimiterMatcher variable default value delimiter matcher to use, may be null * @return {@code this} instance. */ public StrSubstitutor setValueDelimiterMatcher(final StrMatcher valueDelimiterMatcher) { this.valueDelimiterMatcher = valueDelimiterMatcher; return this; } /** * Sets the variable prefix to use. ** The variable prefix is the character or characters that identify the start of a variable. This method allows a single character prefix to be easily set. *
* * @param prefix the prefix character to use. * @return {@code this} instance. */ public StrSubstitutor setVariablePrefix(final char prefix) { return setVariablePrefixMatcher(StrMatcher.charMatcher(prefix)); } /** * Sets the variable prefix to use. ** The variable prefix is the character or characters that identify the start of a variable. This method allows a string prefix to be easily set. *
* * @param prefix the prefix for variables, not null. * @return {@code this} instance. * @throws IllegalArgumentException if the prefix is null. */ public StrSubstitutor setVariablePrefix(final String prefix) { Validate.isTrue(prefix != null, "Variable prefix must not be null!"); return setVariablePrefixMatcher(StrMatcher.stringMatcher(prefix)); } /** * Sets the variable prefix matcher currently in use. ** 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. *
* * @param prefixMatcher the prefix matcher to use, null ignored. * @return {@code this} instance. * @throws IllegalArgumentException if the prefix matcher is null. */ public StrSubstitutor setVariablePrefixMatcher(final StrMatcher prefixMatcher) { Validate.isTrue(prefixMatcher != null, "Variable prefix matcher must not be null!"); this.prefixMatcher = prefixMatcher; return this; } /** * Sets the VariableResolver that is used to lookup variables. * * @param variableResolver the VariableResolver. */ public void setVariableResolver(final StrLookup variableResolver) { this.variableResolver = variableResolver; } /** * Sets the variable suffix to use. ** The variable suffix is the character or characters that identify the end of a variable. This method allows a single character suffix to be easily set. *
* * @param suffix the suffix character to use. * @return {@code this} instance. */ public StrSubstitutor setVariableSuffix(final char suffix) { return setVariableSuffixMatcher(StrMatcher.charMatcher(suffix)); } /** * Sets the variable suffix to use. ** The variable suffix is the character or characters that identify the end of a variable. This method allows a string suffix to be easily set. *
* * @param suffix the suffix for variables, not null. * @return {@code this} instance. * @throws IllegalArgumentException if the suffix is null. */ public StrSubstitutor setVariableSuffix(final String suffix) { Validate.isTrue(suffix != null, "Variable suffix must not be null!"); return setVariableSuffixMatcher(StrMatcher.stringMatcher(suffix)); } /** * Sets the variable suffix matcher currently in use. ** 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. *
* * @param suffixMatcher the suffix matcher to use, null ignored. * @return {@code this} instance. * @throws IllegalArgumentException if the suffix matcher is null. */ public StrSubstitutor setVariableSuffixMatcher(final StrMatcher suffixMatcher) { Validate.isTrue(suffixMatcher != null, "Variable suffix matcher must not be null!"); this.suffixMatcher = suffixMatcher; return this; } /** * Internal method that substitutes the variables. ** Most users of this class do not need to call this method. This method will be called automatically by another (public) method. *
** Writers of subclasses can override this method if they need access to the substitution process at the start or end. *
* * @param buf the string builder to substitute into, not null. * @param offset the start offset within the builder, must be valid. * @param length the length within the builder to be processed, must be valid. * @return true if altered. */ protected boolean substitute(final StrBuilder buf, final int offset, final int length) { return substitute(buf, offset, length, null) > 0; } /** * Recursive handler for multiple levels of interpolation. This is the main interpolation method, which resolves the values of all variable references * contained in the passed in text. * * @param buf the string builder to substitute into, not null. * @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 represents a boolean flag as to whether any change occurred. */ private int substitute(final StrBuilder buf, final int offset, final int length, List* This class can split a String into many smaller strings. It aims * to do a similar job to {@link java.util.StringTokenizer StringTokenizer}, * however it offers much more control and flexibility including implementing * the {@code ListIterator} interface. By default, it is set up * like {@code StringTokenizer}. *
* The input String is split into a number of tokens. * Each token is separated from the next String by a delimiter. * One or more delimiter characters must be specified. *
* Each token may be surrounded by quotes. * The quote matcher specifies the quote character(s). * A quote may be escaped within a quoted section by duplicating itself. *
* Between each token and the delimiter are potentially characters that need trimming. * The trimmer matcher specifies these characters. * One usage might be to trim whitespace characters. *
* At any point outside the quotes there might potentially be invalid characters. * The ignored matcher specifies these characters to be removed. * One usage might be to remove new line characters. *
* Empty tokens may be removed or returned as null. *
* "a,b,c" - Three tokens "a","b","c" (comma delimiter) * " a, b , c " - Three tokens "a","b","c" (default CSV processing trims whitespace) * "a, ", b ,", c" - Three tokens "a, " , " b ", ", c" (quoted text untouched) ** *
| Property | Type | Default | *
|---|---|---|
| delim | CharSetMatcher | { \t\n\r\f} | *
| quote | NoneMatcher | {} | *
| ignore | NoneMatcher | {} | *
| emptyTokenAsNull | boolean | false | *
| ignoreEmptyTokens | boolean | true | *
* You must call a "reset" method to set the string which you want to parse. *
* * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StrTokenizer getCSVInstance() { return getCSVClone(); } /** * Gets a new tokenizer instance which parses Comma Separated Value strings initializing it with the given input. The default for CSV processing will be * trim whitespace from both ends (which can be overridden with the setTrimmer method). * * @param input the text to parse. * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StrTokenizer getCSVInstance(final char[] input) { final StrTokenizer tok = getCSVClone(); tok.reset(input); return tok; } /** * Gets a new tokenizer instance which parses Comma Separated Value strings initializing it with the given input. The default for CSV processing will be * trim whitespace from both ends (which can be overridden with the setTrimmer method). * * @param input the text to parse. * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StrTokenizer getCSVInstance(final String input) { final StrTokenizer tok = getCSVClone(); tok.reset(input); return tok; } /** * Returns a clone of {@code TSV_TOKENIZER_PROTOTYPE}. * * @return a clone of {@code TSV_TOKENIZER_PROTOTYPE}. */ private static StrTokenizer getTSVClone() { return (StrTokenizer) TSV_TOKENIZER_PROTOTYPE.clone(); } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be trim whitespace from both ends (which can * be overridden with the setTrimmer method). ** You must call a "reset" method to set the string which you want to parse. *
* * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StrTokenizer getTSVInstance() { return getTSVClone(); } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be trim whitespace from both ends (which can * be overridden with the setTrimmer method). * * @param input the string to parse. * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StrTokenizer getTSVInstance(final char[] input) { final StrTokenizer tok = getTSVClone(); tok.reset(input); return tok; } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be trim whitespace from both ends (which can * be overridden with the setTrimmer method). * * @param input the string to parse. * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StrTokenizer getTSVInstance(final String input) { final StrTokenizer tok = getTSVClone(); tok.reset(input); return tok; } /** The text to work on. */ private char[] chars; /** The parsed tokens. */ private String[] tokens; /** The current iteration position. */ private int tokenPos; /** The delimiter matcher. */ private StrMatcher delimMatcher = StrMatcher.splitMatcher(); /** The quote matcher. */ private StrMatcher quoteMatcher = StrMatcher.noneMatcher(); /** The ignored matcher. */ private StrMatcher ignoredMatcher = StrMatcher.noneMatcher(); /** The trimmer matcher. */ private StrMatcher trimmerMatcher = StrMatcher.noneMatcher(); /** Whether to return empty tokens as null. */ private boolean emptyAsNull; /** Whether to ignore empty tokens. */ private boolean ignoreEmptyTokens = true; /** * Constructs a tokenizer splitting on space, tab, newline and form feed as per StringTokenizer, but with no text to tokenize. ** This constructor is normally used with {@link #reset(String)}. *
*/ public StrTokenizer() { this.chars = null; } /** * Constructs a tokenizer splitting on space, tab, newline and form feed * as per StringTokenizer. * * @param input the string which is to be parsed, not cloned. */ public StrTokenizer(final char[] input) { if (input == null) { this.chars = null; } else { this.chars = input.clone(); } } /** * Constructs a tokenizer splitting on the specified character. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. */ public StrTokenizer(final char[] input, final char delim) { this(input); setDelimiterChar(delim); } /** * Constructs a tokenizer splitting on the specified delimiter character * and handling quotes using the specified quote character. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StrTokenizer(final char[] input, final char delim, final char quote) { this(input, delim); setQuoteChar(quote); } /** * Constructs a tokenizer splitting on the specified string. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter string. */ public StrTokenizer(final char[] input, final String delim) { this(input); setDelimiterString(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter matcher. */ public StrTokenizer(final char[] input, final StrMatcher delim) { this(input); setDelimiterMatcher(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher * and handling quotes using the specified quote matcher. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StrTokenizer(final char[] input, final StrMatcher delim, final StrMatcher quote) { this(input, delim); setQuoteMatcher(quote); } /** * Constructs a tokenizer splitting on space, tab, newline and form feed * as per StringTokenizer. * * @param input the string which is to be parsed. */ public StrTokenizer(final String input) { if (input != null) { chars = input.toCharArray(); } else { chars = null; } } /** * Constructs a tokenizer splitting on the specified delimiter character. * * @param input the string which is to be parsed. * @param delim the field delimiter character. */ public StrTokenizer(final String input, final char delim) { this(input); setDelimiterChar(delim); } /** * Constructs a tokenizer splitting on the specified delimiter character * and handling quotes using the specified quote character. * * @param input the string which is to be parsed. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StrTokenizer(final String input, final char delim, final char quote) { this(input, delim); setQuoteChar(quote); } /** * Constructs a tokenizer splitting on the specified delimiter string. * * @param input the string which is to be parsed. * @param delim the field delimiter string. */ public StrTokenizer(final String input, final String delim) { this(input); setDelimiterString(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher. * * @param input the string which is to be parsed. * @param delim the field delimiter matcher. */ public StrTokenizer(final String input, final StrMatcher delim) { this(input); setDelimiterMatcher(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher * and handling quotes using the specified quote matcher. * * @param input the string which is to be parsed. * @param delim the field delimiter matcher. * @param quote the field quoted string matcher. */ public StrTokenizer(final String input, final StrMatcher delim, final StrMatcher quote) { this(input, delim); setQuoteMatcher(quote); } /** * Unsupported ListIterator operation. * @param obj this parameter ignored. * @throws UnsupportedOperationException always. */ @Override public void add(final String obj) { throw new UnsupportedOperationException("add() is unsupported"); } /** * Adds a token to a list, paying attention to the parameters we've set. * * @param list the list to add to. * @param tok the token to add. */ private void addToken(final List* 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. */ public StrMatcher getIgnoredMatcher() { return ignoredMatcher; } /** * Gets the quote matcher currently in use. ** 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. */ public StrMatcher getQuoteMatcher() { return quoteMatcher; } /** * Gets a copy of the full token list as an independent modifiable array. * * @return The tokens as a String array. */ public String[] getTokenArray() { checkTokenized(); return tokens.clone(); } /** * Gets a copy of the full token list as an independent modifiable list. * * @return The tokens as a String array. */ public List* 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. */ public StrMatcher getTrimmerMatcher() { return trimmerMatcher; } /** * Checks whether there are any more tokens. * * @return true if there are more tokens. */ @Override public boolean hasNext() { checkTokenized(); return tokenPos < tokens.length; } /** * Checks whether there are any previous tokens that can be iterated to. * * @return true if there are previous tokens. */ @Override public boolean hasPrevious() { checkTokenized(); return tokenPos > 0; } /** * Gets whether the tokenizer currently returns empty tokens as null. * The default for this property is false. * * @return true if empty tokens are returned as null. */ public boolean isEmptyTokenAsNull() { return this.emptyAsNull; } /** * Gets whether the tokenizer currently ignores empty tokens. * The default for this property is true. * * @return true if empty tokens are not returned. */ public boolean isIgnoreEmptyTokens() { return ignoreEmptyTokens; } /** * Checks if the characters at the index specified match the quote * already matched in readNextToken(). * * @param srcChars the character array being tokenized. * @param pos the position to check for a quote. * @param len the length of the character array being tokenized. * @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 true if a quote is matched. */ private boolean isQuote(final char[] srcChars, final int pos, final int len, final int quoteStart, final int quoteLen) { for (int i = 0; i < quoteLen; i++) { if (pos + i >= len || srcChars[pos + i] != srcChars[quoteStart + i]) { return false; } } return true; } /** * Gets the next token. * * @return The next String token. * @throws NoSuchElementException if there are no more elements. */ @Override public String next() { if (hasNext()) { return tokens[tokenPos++]; } throw new NoSuchElementException(); } /** * Gets the index of the next token to return. * * @return The next token index. */ @Override public int nextIndex() { return tokenPos; } /** * 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. */ public String nextToken() { if (hasNext()) { return tokens[tokenPos++]; } return null; } /** * Gets the token previous to the last returned token. * * @return The previous token. */ @Override public String previous() { if (hasPrevious()) { return tokens[--tokenPos]; } throw new NoSuchElementException(); } /** * Gets the index of the previous token. * * @return The previous token index. */ @Override public int previousIndex() { return tokenPos - 1; } /** * Gets the previous token from the String. * * @return The previous sequential token, or null when no more tokens are found. */ public String previousToken() { if (hasPrevious()) { return tokens[--tokenPos]; } return null; } /** * Reads character by character through the String to get the next token. * * @param srcChars the character array being tokenized. * @param start the first character of field. * @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 immediately after the delimiter), or -1 if end of string found. */ private int readNextToken(final char[] srcChars, int start, final int len, final StrBuilder workArea, final List* This method allows the same tokenizer to be reused for the same String. *
* * @return {@code this} instance. */ public StrTokenizer reset() { tokenPos = 0; tokens = null; return this; } /** * Reset this tokenizer, giving it a new input string to parse. In this manner you can re-use a tokenizer with the same settings on multiple input lines. * * @param input the new character array to tokenize, not cloned, null sets no text to parse. * @return {@code this} instance. */ public StrTokenizer reset(final char[] input) { reset(); if (input != null) { this.chars = input.clone(); } else { this.chars = null; } return this; } /** * Reset this tokenizer, giving it a new input string to parse. In this manner you can re-use a tokenizer with the same settings on multiple input lines. * * @param input the new string to tokenize, null sets no text to parse. * @return {@code this} instance. */ public StrTokenizer reset(final String input) { reset(); if (input != null) { this.chars = input.toCharArray(); } else { this.chars = null; } return this; } /** * Unsupported ListIterator operation. * * @param obj this parameter ignored. * @throws UnsupportedOperationException Always thrown. */ @Override public void set(final String obj) { throw new UnsupportedOperationException("set() is unsupported"); } /** * Sets the field delimiter character. * * @param delim the delimiter character to use. * @return {@code this} instance. */ public StrTokenizer setDelimiterChar(final char delim) { return setDelimiterMatcher(StrMatcher.charMatcher(delim)); } /** * Sets the field delimiter matcher. ** The delimiter is used to separate one token from another. *
* * @param delim the delimiter matcher to use. * @return {@code this} instance. */ public StrTokenizer setDelimiterMatcher(final StrMatcher delim) { if (delim == null) { this.delimMatcher = StrMatcher.noneMatcher(); } else { this.delimMatcher = delim; } return this; } /** * Sets the field delimiter string. * * @param delim the delimiter string to use. * @return {@code this} instance. */ public StrTokenizer setDelimiterString(final String delim) { return setDelimiterMatcher(StrMatcher.stringMatcher(delim)); } /** * Sets whether the tokenizer should return empty tokens as null. The default for this property is false. * * @param emptyAsNull whether empty tokens are returned as null. * @return {@code this} instance. */ public StrTokenizer setEmptyTokenAsNull(final boolean emptyAsNull) { this.emptyAsNull = emptyAsNull; return this; } /** * Sets the character to ignore. ** This character is ignored when parsing the String, unless it is within a quoted region. *
* * @param ignored the ignored character to use. * @return {@code this} instance. */ public StrTokenizer setIgnoredChar(final char ignored) { return setIgnoredMatcher(StrMatcher.charMatcher(ignored)); } /** * Sets the matcher for characters to ignore. ** These characters are ignored when parsing the String, unless they are within a quoted region. *
* * @param ignored the ignored matcher to use, null ignored. * @return {@code this} instance. */ public StrTokenizer setIgnoredMatcher(final StrMatcher ignored) { if (ignored != null) { this.ignoredMatcher = ignored; } return this; } /** * Sets whether the tokenizer should ignore and not return empty tokens. The default for this property is true. * * @param ignoreEmptyTokens whether empty tokens are not returned. * @return {@code this} instance. */ public StrTokenizer setIgnoreEmptyTokens(final boolean ignoreEmptyTokens) { this.ignoreEmptyTokens = ignoreEmptyTokens; return this; } /** * Sets the quote character to use. ** The quote character is used to wrap data between the tokens. This enables delimiters to be entered as data. *
* * @param quote the quote character to use. * @return {@code this} instance. */ public StrTokenizer setQuoteChar(final char quote) { return setQuoteMatcher(StrMatcher.charMatcher(quote)); } /** * Sets the quote matcher to use. ** The quote character is used to wrap data between the tokens. This enables delimiters to be entered as data. *
* * @param quote the quote matcher to use, null ignored. * @return {@code this} instance. */ public StrTokenizer setQuoteMatcher(final StrMatcher quote) { if (quote != null) { this.quoteMatcher = quote; } return this; } /** * Sets the matcher for characters to trim. ** These characters are trimmed off on each side of the delimiter until the token or quote is found. *
* * @param trimmer the trimmer matcher to use, null ignored * @return {@code this} instance. */ public StrTokenizer setTrimmerMatcher(final StrMatcher trimmer) { if (trimmer != null) { this.trimmerMatcher = trimmer; } return this; } /** * Gets the number of tokens found in the String. * * @return The number of matched tokens. */ public int size() { checkTokenized(); return tokens.length; } /** * Internal method to performs the tokenization. ** Most users of this class do not need to call this method. This method will be called automatically by other (public) methods when required. *
** This method exists to allow subclasses to add code before or after the tokenization. For example, a subclass could alter the character array, offset or * count to be parsed, or call the tokenizer multiple times on multiple strings. It is also be possible to filter the results. *
** {@code StrTokenizer} will always pass a zero offset and a count equal to the length of the array to this method, however a subclass may pass other * values, or even an entirely different array. *
* * @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. */ protected List* Escapes and unescapes {@code String}s for Java, Java Script, HTML and XML. *
* ** #ThreadSafe# *
* ** This code has been adapted from Apache Commons Lang 3.5. *
* * @since 1.0 */ public class StringEscapeUtils { /* ESCAPE TRANSLATORS */ /** * Convenience wrapper for {@link StringBuilder} providing escape methods. * *Example:
*
* new Builder(ESCAPE_HTML4)
* .append("<p>")
* .escape("This is paragraph 1 and special chars like & get escaped.")
* .append("</p><p>")
* .escape("This is paragraph 2 & more...")
* .append("</p>")
* .toString()
*
*/
public static final class Builder {
/**
* StringBuilder to be used in the Builder class.
*/
private final StringBuilder sb;
/**
* CharSequenceTranslator to be used in the Builder class.
*/
private final CharSequenceTranslator translator;
/**
* Builder constructor.
*
* @param translator a CharSequenceTranslator.
*/
private Builder(final CharSequenceTranslator translator) {
this.sb = new StringBuilder();
this.translator = translator;
}
/**
* Literal append, no escaping being done.
*
* @param input the String to append
* @return {@code this}, to enable chaining
*/
public Builder append(final String input) {
sb.append(input);
return this;
}
/**
* Escape {@code input} according to the given {@link CharSequenceTranslator}.
*
* @param input the String to escape
* @return {@code this}, to enable chaining
*/
public Builder escape(final String input) {
sb.append(translator.translate(input));
return this;
}
/**
* Return the escaped string.
*
* @return The escaped string
*/
@Override
public String toString() {
return sb.toString();
}
}
/**
* Translator object for unescaping backslash escaped entries.
*/
static class XsiUnescaper extends CharSequenceTranslator {
/**
* Escaped backslash constant.
*/
private static final char BACKSLASH = '\\';
@Override
public int translate(final CharSequence input, final int index, final Writer writer) throws IOException {
if (index != 0) {
throw new IllegalStateException("XsiUnescaper should never reach the [1] index");
}
final String s = input.toString();
int segmentStart = 0;
int searchOffset = 0;
while (true) {
final int pos = s.indexOf(BACKSLASH, searchOffset);
if (pos == -1) {
if (segmentStart < s.length()) {
writer.write(s.substring(segmentStart));
}
break;
}
if (pos > segmentStart) {
writer.write(s.substring(segmentStart, pos));
}
segmentStart = pos + 1;
searchOffset = pos + 2;
}
return Character.codePointCount(input, 0, input.length());
}
}
/**
* Translator object for escaping Java.
*
* While {@link #escapeJava(String)} is the expected method of use, this object allows the Java escaping functionality to be used as the foundation for a
* custom translator.
*/
public static final CharSequenceTranslator ESCAPE_JAVA;
static {
final Map* If the value contains a comma, newline or double quote, then the String value is returned enclosed in double quotes. *
* ** Any double quote characters in the value are escaped with another double quote. *
* ** If the value does not contain a comma, newline or double quote, then the String value is returned unchanged. *
** See Wikipedia and RFC 4180. *
* * @param input the input CSV column String, may be null. * @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 String escapeCsv(final String input) { return ESCAPE_CSV.translate(input); } /** * Escapes the characters in a {@code String} using EcmaScript String rules. * ** Escapes any values it finds into their EcmaScript String form. Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) *
* ** So a tab becomes the characters {@code '\\'} and {@code 't'}. *
* ** The only difference between Java strings and EcmaScript strings is that in EcmaScript, a single quote and forward-slash (/) are escaped. *
* ** Note that EcmaScript is best known by the JavaScript and ActionScript dialects. *
* ** Example: *
* *
* input string: He didn't say, "Stop!"
* output string: He didn\'t say, \"Stop!\"
*
* * Security Note. We only provide backslash escaping in this method. For example, {@code '\"'} has the output {@code '\\\"'} which could * result in potential issues in the case where the string being escaped is being used in an HTML tag like {@code }. If you wish * to have more rigorous string escaping, you may consider the ESAPI * Libraries. Further, you can view the ESAPI GitHub Org. *
* * @param input String to escape values in, may be null. * @return String with escaped values, {@code null} if null string input. */ public static String escapeEcmaScript(final String input) { return ESCAPE_ECMASCRIPT.translate(input); } /** * Escapes the characters in a {@code String} using HTML entities. * *Supports only the HTML 3.0 entities.
* * @param input the {@code String} to escape, may be null. * @return a new escaped {@code String}, {@code null} if null string input. */ public static String escapeHtml3(final String input) { return ESCAPE_HTML3.translate(input); } // HTML and XML /** * Escapes the characters in a {@code String} using HTML entities. * ** For example: *
*{@code "bread" & "butter"}
* becomes: ** {@code "bread" & "butter"}. *
* *Supports all known HTML 4.0 entities, including funky accents. * Note that the commonly used apostrophe escape character (') * is not a legal entity and so is not supported).
* * @param input the {@code String} to escape, may be null. * @return a new escaped {@code String}, {@code null} if null string input. * @see ISO Entities * @see HTML 3.2 Character Entities for ISO Latin-1 * @see HTML 4.0 Character entity references * @see HTML 4.01 Character References * @see HTML 4.01 Code positions */ public static String escapeHtml4(final String input) { return ESCAPE_HTML4.translate(input); } // Java and JavaScript /** * Escapes the characters in a {@code String} using Java String rules. * ** Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) *
* ** So a tab becomes the characters {@code '\\'} and {@code 't'}. *
* ** The only difference between Java strings and JavaScript strings is that in JavaScript, a single quote and forward-slash (/) are escaped. *
* ** Example: *
* *
* input string: He didn't say, "Stop!"
* output string: He didn't say, \"Stop!\"
*
*
* @param input String to escape values in, may be null.
* @return String with escaped values, {@code null} if null string input.
*/
public static String escapeJava(final String input) {
return ESCAPE_JAVA.translate(input);
}
/**
* Escapes the characters in a {@code String} using Json String rules.
*
* * Escapes any values it finds into their Json String form. Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) *
* ** So a tab becomes the characters {@code '\\'} and {@code 't'}. *
* ** The only difference between Java strings and Json strings is that in Json, forward-slash (/) is escaped. *
* ** See http://www.ietf.org/rfc/rfc4627.txt for further details. *
* ** Example: *
* *
* input string: He didn't say, "Stop!"
* output string: He didn't say, \"Stop!\"
*
*
* @param input String to escape values in, may be null.
* @return String with escaped values, {@code null} if null string input.
*/
public static String escapeJson(final String input) {
return ESCAPE_JSON.translate(input);
}
/**
* Escapes the characters in a {@code String} using XML entities.
*
* * For example: {@code "bread" & "butter"} => {@code "bread" & "butter"}. *
* ** Note that XML 1.0 is a text-only format: it cannot represent control characters or unpaired Unicode surrogate code points, even after escaping. * {@code escapeXml10} will remove characters that do not fit in the following ranges: *
* ** {@code #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]} *
* ** Though not strictly necessary, {@code escapeXml10} will escape characters in the following ranges: *
* ** {@code [#x7F-#x84] | [#x86-#x9F]} *
* ** The returned string can be inserted into a valid XML 1.0 or XML 1.1 document. If you want to allow more non-text characters in an XML 1.1 document, use * {@link #escapeXml11(String)}. *
* * @param input the {@code String} to escape, may be null. * @return a new escaped {@code String}, {@code null} if null string input. * @see #unescapeXml(String) */ public static String escapeXml10(final String input) { return ESCAPE_XML10.translate(input); } /** * Escapes the characters in a {@code String} using XML entities. * ** For example: {@code "bread" & "butter"} => {@code "bread" & "butter"}. *
* ** XML 1.1 can represent certain control characters, but it cannot represent the null byte or unpaired Unicode surrogate code points, even after escaping. * {@code escapeXml11} will remove characters that do not fit in the following ranges: *
* ** {@code [#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]} *
* ** {@code escapeXml11} will escape characters in the following ranges: *
* ** {@code [#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]} *
* ** The returned string can be inserted into a valid XML 1.1 document. Do not use it for XML 1.0 documents. *
* * @param input the {@code String} to escape, may be null. * @return a new escaped {@code String}, {@code null} if null string input. * @see #unescapeXml(String) */ public static String escapeXml11(final String input) { return ESCAPE_XML11.translate(input); } /** * Escapes the characters in a {@code String} using XSI rules. * ** Beware! In most cases you don't want to escape shell commands but use multi-argument methods provided by {@link ProcessBuilder} or * {@link Runtime#exec(String[])} instead. *
* ** Example: *
* *
* input string: He didn't say, "Stop!"
* output string: He\ didn\'t\ say,\ \"Stop!\"
*
*
* @param input String to escape values in, may be null.
* @return String with escaped values, {@code null} if null string input.
* @see Shell Command Language
*/
public static String escapeXSI(final String input) {
return ESCAPE_XSI.translate(input);
}
/**
* Returns a {@code String} value for an unescaped CSV column.
*
* * If the value is enclosed in double quotes, and contains a comma, newline or double quote, then quotes are removed. *
* ** Any double quote escaped characters (a pair of double quotes) are unescaped to just one double quote. *
* ** If the value is not enclosed in double quotes, or is and does not contain a comma, newline or double quote, then the String value is returned unchanged. *
* * see Wikipedia and RFC 4180. * * @param input the input CSV column String, may be null. * @return The input String, with enclosing double quotes removed and embedded double quotes unescaped, {@code null} if null string input. */ public static String unescapeCsv(final String input) { return UNESCAPE_CSV.translate(input); } /** * Unescapes any EcmaScript literals found in the {@code String}. * ** For example, it will turn a sequence of {@code '\'} and {@code 'n'} into a newline character, unless the {@code '\'} is preceded by another {@code '\'}. *
* * @param input the {@code String} to unescape, may be null. * @return A new unescaped {@code String}, {@code null} if null string input. * @see #unescapeJava(String) */ public static String unescapeEcmaScript(final String input) { return UNESCAPE_ECMASCRIPT.translate(input); } /** * Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports only HTML 3.0 * entities. * * @param input the {@code String} to unescape, may be null. * @return a new unescaped {@code String}, {@code null} if null string input. */ public static String unescapeHtml3(final String input) { return UNESCAPE_HTML3.translate(input); } /** * Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports HTML 4.0 * entities. * *
* For example, the string {@code "<Français>"} will become {@code "
* If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. e.g. {@code ">&zzzz;x"} will become {@code ">&zzzz;x"}. *
* * @param input the {@code String} to unescape, may be null. * @return a new unescaped {@code String}, {@code null} if null string input. */ public static String unescapeHtml4(final String input) { return UNESCAPE_HTML4.translate(input); } /** * Unescapes any Java literals found in the {@code String}. For example, it will turn a sequence of {@code '\'} and {@code 'n'} into a newline character, * unless the {@code '\'} is preceded by another {@code '\'}. * * @param input the {@code String} to unescape, may be null. * @return a new unescaped {@code String}, {@code null} if null string input. */ public static String unescapeJava(final String input) { return UNESCAPE_JAVA.translate(input); } /** * Unescapes any Json literals found in the {@code String}. * ** For example, it will turn a sequence of {@code '\'} and {@code 'n'} into a newline character, unless the {@code '\'} is preceded by another {@code '\'}. *
* * @param input the {@code String} to unescape, may be null. * @return A new unescaped {@code String}, {@code null} if null string input. * @see #unescapeJava(String) */ public static String unescapeJson(final String input) { return UNESCAPE_JSON.translate(input); } /** * Unescapes a string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes. * ** Supports only the five basic XML entities (gt, lt, quot, amp, apos). Does not support DTDs or external entities. *
* ** Note that numerical \\u Unicode codes are unescaped to their respective Unicode characters. This may change in future releases. *
* * @param input the {@code String} to unescape, may be null. * @return a new unescaped {@code String}, {@code null} if null string input. * @see #escapeXml10(String) * @see #escapeXml11(String) */ public static String unescapeXml(final String input) { return UNESCAPE_XML.translate(input); } /** * Unescapes the characters in a {@code String} using XSI rules. * * @param input the {@code String} to unescape, may be null. * @return a new unescaped {@code String}, {@code null} if null string input. * @see StringEscapeUtils#escapeXSI(String) */ public static String unescapeXSI(final String input) { return UNESCAPE_XSI.translate(input); } /** * {@code StringEscapeUtils} instances should NOT be constructed in standard programming. * ** Instead, the class should be used as: *
* *
* StringEscapeUtils.escapeJava("foo");
*
*
* * This constructor is public to permit tools that require a JavaBean instance to operate. *
*/ public StringEscapeUtils() { } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/StringSubstitutor.java 0000664 0000000 0000000 00000200561 15114327406 0033161 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.util.ArrayList; import java.util.List; import java.util.Map; import java.util.Objects; import java.util.Properties; import java.util.function.Function; import java.util.stream.Collectors; import org.apache.commons.lang3.Validate; import org.apache.commons.text.lookup.StringLookup; import org.apache.commons.text.lookup.StringLookupFactory; import org.apache.commons.text.matcher.StringMatcher; import org.apache.commons.text.matcher.StringMatcherFactory; /** * Substitutes variables within a string by values. ** This class takes a piece of text and substitutes all the variables within it. The default definition of a variable is * {@code ${variableName}}. The prefix and suffix can be changed via constructors and set methods. *
** Variable values are typically resolved from a map, but could also be resolved from system properties, or by supplying * a custom variable resolver. *
** The simplest example is to use this class to replace Java System properties. For example: *
* *
* StringSubstitutor
* .replaceSystemProperties("You are running with java.version = ${java.version} and os.name = ${os.name}.");
*
*
* * Typical usage of this class follows the following pattern: *
** For example: *
* *
* // Build map
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("animal", "quick brown fox");
* valuesMap.put("target", "lazy dog");
* String templateString = "The ${animal} jumped over the ${target}.";
*
* // Build StringSubstitutor
* StringSubstitutor sub = new StringSubstitutor(valuesMap);
*
* // Replace
* String resolvedString = sub.replace(templateString);
*
*
* * yielding: *
* ** "The quick brown fox jumped over the lazy dog." ** *
* You can set a default value for unresolved variables. The default value for a variable can be appended to the * variable name after the variable default value delimiter. The default value of the variable default value delimiter * is ":-", as in bash and other *nix shells. *
** You can set the variable value delimiter with {@link #setValueDelimiterMatcher(StringMatcher)}, * {@link #setValueDelimiter(char)} or {@link #setValueDelimiter(String)}. *
** For example: *
* *
* // Build map
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("animal", "quick brown fox");
* valuesMap.put("target", "lazy dog");
* String templateString = "The ${animal} jumped over the ${target} ${undefined.number:-1234567890} times.";
*
* // Build StringSubstitutor
* StringSubstitutor sub = new StringSubstitutor(valuesMap);
*
* // Replace
* String resolvedString = sub.replace(templateString);
*
*
* * yielding: *
* ** "The quick brown fox jumped over the lazy dog 1234567890 times." ** *
* {@code StringSubstitutor} supports throwing exceptions for unresolved variables, you enable this by setting calling * {@link #setEnableUndefinedVariableException(boolean)} with {@code true}. *
* ** Static shortcut methods cover the most common use cases. If multiple replace operations are to be performed, creating * and reusing an instance of this class will be more efficient. *
* ** The default interpolator lets you use string lookups like: *
* *
* final StringSubstitutor interpolator = StringSubstitutor.createInterpolator();
* final String text = interpolator.replace(
* "Base64 Decoder: ${base64Decoder:SGVsbG9Xb3JsZCE=}\n"
* + "Base64 Encoder: ${base64Encoder:HelloWorld!}\n"
* + "Java Constant: ${const:java.awt.event.KeyEvent.VK_ESCAPE}\n"
* + "Date: ${date:yyyy-MM-dd}\n"
* + "Environment Variable: ${env:USERNAME}\n"
* + "File Content: ${file:UTF-8:src/test/resources/document.properties}\n"
* + "Java: ${java:version}\n"
* + "Localhost: ${localhost:canonical-name}\n"
* + "Properties File: ${properties:src/test/resources/document.properties::mykey}\n"
* + "Resource Bundle: ${resourceBundle:org.apache.commons.text.example.testResourceBundleLookup:mykey}\n"
* + "System Property: ${sys:user.dir}\n"
* + "URL Decoder: ${urlDecoder:Hello%20World%21}\n"
* + "URL Encoder: ${urlEncoder:Hello World!}\n"
* + "XML XPath: ${xml:src/test/resources/document.xml:/root/path/to/node}\n");
*
* * For documentation and a full list of available lookups, see {@link StringLookupFactory}. *
*NOTE: The list of lookups available by default in {@link #createInterpolator()} changed * in version {@code 1.10.0}. See the {@link StringLookupFactory} documentation for details and an explanation * on how to reproduce the previous functionality. *
* ** Variable replacement can work recursively by calling {@link #setEnableSubstitutionInVariables(boolean)} with * {@code true}. If a variable value contains a variable then that variable will also be replaced. Cyclic replacements * are detected and will throw an exception. *
** You can get the replace result to contain a variable prefix. For example: *
* *
* "The variable ${${name}} must be used."
*
*
* * If the value of the "name" variable is "x", then only the variable "name" is replaced resulting in: *
* *
* "The variable ${x} must be used."
*
*
* * To achieve this effect there are two possibilities: Either set a different prefix and suffix for variables which do * not conflict with the result text you want to produce. The other possibility is to use the escape character, by * default '$'. If this character is placed before a variable reference, this reference is ignored and won't be * replaced. For example: *
* *
* "The variable $${${name}} must be used."
*
* * In some complex scenarios you might even want to perform substitution in the names of variables, for instance *
* *
* ${jre-${java.specification.version}}
*
*
* * {@code StringSubstitutor} supports this recursive substitution in variable names, but it has to be enabled explicitly * by calling {@link #setEnableSubstitutionInVariables(boolean)} with {@code true}. *
* ** This class is not thread safe. *
* * @since 1.3 */ public class StringSubstitutor { /** * The low-level result of a substitution. * * @since 1.9 */ private static final class Result { /** Whether the buffer is altered. */ public final boolean altered; /** The length of change. */ public final int lengthChange; private Result(final boolean altered, final int lengthChange) { this.altered = altered; this.lengthChange = lengthChange; } @Override public String toString() { return "Result [altered=" + altered + ", lengthChange=" + lengthChange + "]"; } } /** * Constant for the default escape character. */ public static final char DEFAULT_ESCAPE = '$'; /** * The default variable default separator. * * @since 1.5. */ public static final String DEFAULT_VAR_DEFAULT = ":-"; /** * The default variable end separator. * * @since 1.5. */ public static final String DEFAULT_VAR_END = "}"; /** * The default variable start separator. * * @since 1.5. */ public static final String DEFAULT_VAR_START = "${"; /** * Constant for the default variable prefix. */ public static final StringMatcher DEFAULT_PREFIX = StringMatcherFactory.INSTANCE.stringMatcher(DEFAULT_VAR_START); /** * Constant for the default variable suffix. */ public static final StringMatcher DEFAULT_SUFFIX = StringMatcherFactory.INSTANCE.stringMatcher(DEFAULT_VAR_END); /** * Constant for the default value delimiter of a variable. */ public static final StringMatcher DEFAULT_VALUE_DELIMITER = StringMatcherFactory.INSTANCE .stringMatcher(DEFAULT_VAR_DEFAULT); /** * Creates a new instance using the interpolator string lookup * {@link StringLookupFactory#interpolatorStringLookup()}. ** This StringSubstitutor lets you perform substitutions like: *
* *
* StringSubstitutor.createInterpolator().replace(
* "OS name: ${sys:os.name}, user: ${env:USER}");
*
*
* The table below lists the lookups available by default in the returned instance. These * may be modified through the use of the * {@value org.apache.commons.text.lookup.StringLookupFactory#DEFAULT_STRING_LOOKUPS_PROPERTY} * system property, as described in the {@link StringLookupFactory} documentation.
* *NOTE: The list of lookups available by default changed in version {@code 1.10.0}. * Configuration via system property (as mentioned above) may be necessary to reproduce previous functionality. *
* *| Key | *Lookup | *
|---|---|
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_BASE64_DECODER} | *{@link StringLookupFactory#base64DecoderStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_BASE64_ENCODER} | *{@link StringLookupFactory#base64EncoderStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_CONST} | *{@link StringLookupFactory#constantStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_DATE} | *{@link StringLookupFactory#dateStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_ENV} | *{@link StringLookupFactory#environmentVariableStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_FILE} | *{@link StringLookupFactory#fileStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_JAVA} | *{@link StringLookupFactory#javaPlatformStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_LOCALHOST} | *{@link StringLookupFactory#localHostStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_LOOPBACK_ADDRESS} | *{@link StringLookupFactory#loopbackAddressStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_PROPERTIES} | *{@link StringLookupFactory#propertiesStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_RESOURCE_BUNDLE} | *{@link StringLookupFactory#resourceBundleStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_SYS} | *{@link StringLookupFactory#systemPropertyStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_URL_DECODER} | *{@link StringLookupFactory#urlDecoderStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_URL_ENCODER} | *{@link StringLookupFactory#urlEncoderStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_XML} | *{@link StringLookupFactory#xmlStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_XML_DECODER} | *{@link StringLookupFactory#xmlDecoderStringLookup()} | *
| {@value org.apache.commons.text.lookup.StringLookupFactory#KEY_XML_ENCODER} | *{@link StringLookupFactory#xmlEncoderStringLookup()} | *
* The variable default value delimiter is the character or characters that delimit the variable name and the * variable default value. This delimiter is expressed in terms of a matcher allowing advanced variable default * value delimiter matches. *
** If it returns null, then the variable default value resolution is disabled. * * @return The variable default value delimiter matcher in use, may be null. */ public StringMatcher getValueDelimiterMatcher() { return valueDelimiterMatcher; } /** * Gets the variable prefix matcher currently in use. *
* 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 */ public StringMatcher getVariablePrefixMatcher() { return prefixMatcher; } /** * Gets the variable suffix matcher currently in use. ** 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 */ public StringMatcher getVariableSuffixMatcher() { return suffixMatcher; } /** * Returns a flag whether substitution is disabled in variable values.If set to true, the values of variables * can contain other variables will not be processed and substituted original variable is evaluated, e.g. * *
* Map<String, String> valuesMap = new HashMap<>();
* valuesMap.put("name", "Douglas ${surname}");
* valuesMap.put("surname", "Crockford");
* String templateString = "Hi ${name}";
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
*
*
* yielding:
*
*
* Hi Douglas ${surname}
*
*
* @return The substitution in variable values flag.
*/
public boolean isDisableSubstitutionInValues() {
return disableSubstitutionInValues;
}
/**
* Returns a flag whether substitution is done in variable names.
*
* @return The substitution in variable names flag.
*/
public boolean isEnableSubstitutionInVariables() {
return enableSubstitutionInVariables;
}
/**
* Returns a flag whether exception can be thrown upon undefined variable.
*
* @return The fail on undefined variable flag.
*/
public boolean isEnableUndefinedVariableException() {
return failOnUndefinedVariable;
}
/**
* Returns the flag controlling whether escapes are preserved during substitution.
*
* @return The preserve escape flag.
*/
public boolean isPreserveEscapes() {
return preserveEscapes;
}
/**
* Replaces all the occurrences of variables with their matching values from the resolver using the given source
* array as a template. 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.
* @throws IllegalArgumentException if variable is not found when its allowed to throw exception.
*/
public String replace(final char[] source) {
if (source == null) {
return null;
}
final TextStringBuilder buf = new TextStringBuilder(source.length).append(source);
substitute(buf, 0, source.length);
return buf.toString();
}
/**
* Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not
* altered by this method.
* * Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned. *
* * @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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. * @throws StringIndexOutOfBoundsException if {@code offset} is not in the range {@code 0 <= offset <= chars.length}. * @throws StringIndexOutOfBoundsException if {@code length < 0}. * @throws StringIndexOutOfBoundsException if {@code offset + length > chars.length}. */ public String replace(final char[] source, final int offset, final int length) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source as * a template. 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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final CharSequence source) { if (source == null) { return null; } return replace(source, 0, source.length()); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source as * a template. The source is not altered by this method. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not * returned. *
* * @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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final CharSequence source, final int offset, final int length) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(length).append(source.toString(), offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables in the given source object with their matching values from the * resolver. The input source object is converted to a string using {@code toString} and is not altered. * * @param source the source to replace in, null returns null. * @return The result of the replace operation. * @throws IllegalArgumentException if a variable is not found and enableUndefinedVariableException is true. */ public String replace(final Object source) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder().append(source); substitute(buf, 0, buf.length()); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values 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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final String source) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(source); if (!substitute(buf, 0, source.length())) { return source; } return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template. ** Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned. *
* * @param source the string to replace in, null returns null. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return The result of the replace operation. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. * @throws StringIndexOutOfBoundsException if {@code offset} is not in the range {@code 0 <= offset <= source.length()}. * @throws StringIndexOutOfBoundsException if {@code length < 0}. * @throws StringIndexOutOfBoundsException if {@code offset + length > source.length()}. */ public String replace(final String source, final int offset, final int length) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return source.substring(offset, offset + length); } return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source * buffer as a template. 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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final StringBuffer source) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(source.length()).append(source); substitute(buf, 0, buf.length()); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source * buffer as a template. The buffer is not altered by this method. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not * returned. *
* * @param source the buffer to use as a template, not changed, null returns null. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return The result of the replace operation. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final StringBuffer source, final int offset, final int length) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source * builder as a template. 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. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final TextStringBuilder source) { if (source == null) { return null; } final TextStringBuilder builder = new TextStringBuilder(source.length()).append(source); substitute(builder, 0, builder.length()); return builder.toString(); } /** * Replaces all the occurrences of variables with their matching values from the resolver using the given source * builder as a template. The builder is not altered by this method. ** Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not * returned. *
* * @param source the builder to use as a template, not changed, null returns null. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return The result of the replace operation. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public String replace(final TextStringBuilder source, final int offset, final int length) { if (source == null) { return null; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); substitute(buf, 0, length); return buf.toString(); } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the * resolver. The buffer is updated with the result. * * @param source the buffer to replace in, updated, null returns zero. * @return true if altered */ public boolean replaceIn(final StringBuffer source) { if (source == null) { return false; } return replaceIn(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the * resolver. The buffer is updated with the result. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is * not deleted. *
* * @param source the buffer to replace in, updated, null returns zero. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return true if altered. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public boolean replaceIn(final StringBuffer source, final int offset, final int length) { if (source == null) { return false; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return false; } source.replace(offset, offset + length, buf.toString()); return true; } /** * Replaces all the occurrences of variables within the given source buffer with their matching values from the * resolver. The buffer is updated with the result. * * @param source the buffer to replace in, updated, null returns zero. * @return true if altered. */ public boolean replaceIn(final StringBuilder source) { if (source == null) { return false; } return replaceIn(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the * resolver. The builder is updated with the result. ** Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is * not deleted. *
* * @param source the buffer to replace in, updated, null returns zero. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return true if altered. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public boolean replaceIn(final StringBuilder source, final int offset, final int length) { if (source == null) { return false; } final TextStringBuilder buf = new TextStringBuilder(length).append(source, offset, length); if (!substitute(buf, 0, length)) { return false; } source.replace(offset, offset + length, buf.toString()); return true; } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the * resolver. * * @param source the builder to replace in, updated, null returns zero. * @return true if altered. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public boolean replaceIn(final TextStringBuilder source) { if (source == null) { return false; } return substitute(source, 0, source.length()); } /** * Replaces all the occurrences of variables within the given source builder with their matching values from the * resolver. ** Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is * not deleted. *
* * @param source the builder to replace in, null returns zero. * @param offset the start offset within the source, must be valid. * @param length the length within the source to be processed, must be valid. * @return true if altered. * @throws IllegalArgumentException if variable is not found when its allowed to throw exception. */ public boolean replaceIn(final TextStringBuilder source, final int offset, final int length) { if (source == null) { return false; } return substitute(source, offset, length); } /** * Internal method that resolves the value of a variable. ** Most users of this class do not need to call this method. This method is called automatically by the substitution * process. *
** Writers of subclasses can override this method if they need to alter how each substitution occurs. The method is * passed the variable's name and must return the corresponding value. This implementation uses the * {@link #getStringLookup()} with the variable's name as the key. *
* * @param variableName the name of the variable, not null. * @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 null if the variable is unknown. */ protected String resolveVariable(final String variableName, final TextStringBuilder buf, final int startPos, final int endPos) { final StringLookup resolver = getStringLookup(); if (resolver == null) { return null; } return resolver.apply(variableName); } /** * Sets a flag whether substitution is done in variable values (recursive). * * @param disableSubstitutionInValues true if substitution in variable value are disabled. * @return {@code this} instance. */ public StringSubstitutor setDisableSubstitutionInValues(final boolean disableSubstitutionInValues) { this.disableSubstitutionInValues = disableSubstitutionInValues; return this; } /** * Sets a flag whether substitution is done in variable names. If set to true, the names of variables can * contain other variables which are processed first before the original variable is evaluated, e.g. * {@code ${jre-${java.version}}}. The default value is false. * * @param enableSubstitutionInVariables the new value of the flag. * @return {@code this} instance. */ public StringSubstitutor setEnableSubstitutionInVariables(final boolean enableSubstitutionInVariables) { this.enableSubstitutionInVariables = enableSubstitutionInVariables; return this; } /** * Sets a flag whether exception should be thrown if any variable is undefined. * * @param failOnUndefinedVariable true if exception should be thrown on undefined variable. * @return {@code this} instance. */ public StringSubstitutor setEnableUndefinedVariableException(final boolean failOnUndefinedVariable) { this.failOnUndefinedVariable = failOnUndefinedVariable; return this; } /** * Sets the escape character. If this character is placed before a variable reference in the source text, this * variable will be ignored. * * @param escapeChar the escape character (0 for disabling escaping). * @return {@code this} instance. */ public StringSubstitutor setEscapeChar(final char escapeChar) { this.escapeChar = escapeChar; return this; } /** * Sets a flag controlling whether escapes are preserved during substitution. If set to true, the escape * character is retained during substitution (e.g. {@code $${this-is-escaped}} remains {@code $${this-is-escaped}}). * If set to false, the escape character is removed during substitution (e.g. {@code $${this-is-escaped}} * becomes {@code ${this-is-escaped}}). The default value is false * * @param preserveEscapes true if escapes are to be preserved. * @return {@code this} instance. */ public StringSubstitutor setPreserveEscapes(final boolean preserveEscapes) { this.preserveEscapes = preserveEscapes; return this; } /** * Sets the variable default value delimiter to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the * variable default value. This method allows a single character variable default value delimiter to be easily set. *
* * @param valueDelimiter the variable default value delimiter character to use. * @return {@code this} instance. */ public StringSubstitutor setValueDelimiter(final char valueDelimiter) { return setValueDelimiterMatcher(StringMatcherFactory.INSTANCE.charMatcher(valueDelimiter)); } /** * Sets the variable default value delimiter to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the * variable default value. This method allows a string variable default value delimiter to be easily set. *
** If the {@code valueDelimiter} is null or empty string, then the variable default value resolution becomes * disabled. *
* * @param valueDelimiter the variable default value delimiter string to use, may be null or empty. * @return {@code this} instance. */ public StringSubstitutor setValueDelimiter(final String valueDelimiter) { if (valueDelimiter == null || valueDelimiter.isEmpty()) { setValueDelimiterMatcher(null); return this; } return setValueDelimiterMatcher(StringMatcherFactory.INSTANCE.stringMatcher(valueDelimiter)); } /** * Sets the variable default value delimiter matcher to use. ** The variable default value delimiter is the character or characters that delimit the variable name and the * variable default value. This delimiter is expressed in terms of a matcher allowing advanced variable default * value delimiter matches. *
** If the {@code valueDelimiterMatcher} is null, then the variable default value resolution becomes disabled. *
* * @param valueDelimiterMatcher variable default value delimiter matcher to use, may be null. * @return {@code this} instance. */ public StringSubstitutor setValueDelimiterMatcher(final StringMatcher valueDelimiterMatcher) { this.valueDelimiterMatcher = valueDelimiterMatcher; return this; } /** * Sets the variable prefix to use. ** The variable prefix is the character or characters that identify the start of a variable. This method allows a * single character prefix to be easily set. *
* * @param prefix the prefix character to use. * @return {@code this} instance. */ public StringSubstitutor setVariablePrefix(final char prefix) { return setVariablePrefixMatcher(StringMatcherFactory.INSTANCE.charMatcher(prefix)); } /** * Sets the variable prefix to use. ** The variable prefix is the character or characters that identify the start of a variable. This method allows a * string prefix to be easily set. *
* * @param prefix the prefix for variables, not null. * @return {@code this} instance. * @throws IllegalArgumentException if the prefix is null. */ public StringSubstitutor setVariablePrefix(final String prefix) { Validate.isTrue(prefix != null, "Variable prefix must not be null!"); return setVariablePrefixMatcher(StringMatcherFactory.INSTANCE.stringMatcher(prefix)); } /** * Sets the variable prefix matcher currently in use. ** 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. *
* * @param prefixMatcher the prefix matcher to use, null ignored. * @return {@code this} instance. * @throws IllegalArgumentException if the prefix matcher is null. */ public StringSubstitutor setVariablePrefixMatcher(final StringMatcher prefixMatcher) { Validate.isTrue(prefixMatcher != null, "Variable prefix matcher must not be null!"); this.prefixMatcher = prefixMatcher; return this; } /** * Sets the VariableResolver that is used to lookup variables. * * @param variableResolver the VariableResolver. * @return {@code this} instance. */ public StringSubstitutor setVariableResolver(final StringLookup variableResolver) { this.variableResolver = variableResolver; return this; } /** * Sets the variable suffix to use. ** The variable suffix is the character or characters that identify the end of a variable. This method allows a * single character suffix to be easily set. *
* * @param suffix the suffix character to use. * @return {@code this} instance. */ public StringSubstitutor setVariableSuffix(final char suffix) { return setVariableSuffixMatcher(StringMatcherFactory.INSTANCE.charMatcher(suffix)); } /** * Sets the variable suffix to use. ** The variable suffix is the character or characters that identify the end of a variable. This method allows a * string suffix to be easily set. *
* * @param suffix the suffix for variables, not null. * @return {@code this} instance. * @throws IllegalArgumentException if the suffix is null. */ public StringSubstitutor setVariableSuffix(final String suffix) { Validate.isTrue(suffix != null, "Variable suffix must not be null!"); return setVariableSuffixMatcher(StringMatcherFactory.INSTANCE.stringMatcher(suffix)); } /** * Sets the variable suffix matcher currently in use. ** 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. *
* * @param suffixMatcher the suffix matcher to use, null ignored. * @return {@code this} instance. * @throws IllegalArgumentException if the suffix matcher is null. */ public StringSubstitutor setVariableSuffixMatcher(final StringMatcher suffixMatcher) { Validate.isTrue(suffixMatcher != null, "Variable suffix matcher must not be null!"); this.suffixMatcher = suffixMatcher; return this; } /** * Internal method that substitutes the variables. ** Most users of this class do not need to call this method. This method will be called automatically by another * (public) method. *
** Writers of subclasses can override this method if they need access to the substitution process at the start or * end. *
* * @param builder the string builder to substitute into, not null. * @param offset the start offset within the builder, must be valid. * @param length the length within the builder to be processed, must be valid. * @return true if altered. */ protected boolean substitute(final TextStringBuilder builder, final int offset, final int length) { return substitute(builder, offset, length, null).altered; } /** * Recursive handler for multiple levels of interpolation. This is the main interpolation method, which resolves the * values of all variable references contained in the passed in text. * * @param builder the string builder to substitute into, not null. * @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 result. * @throws IllegalArgumentException if variable is not found andisEnableUndefinedVariableException() == true.
* @since 1.9
*/
private Result substitute(final TextStringBuilder builder, final int offset, final int length,
List* This class can split a String into many smaller strings. It aims to do a similar job to * {@link java.util.StringTokenizer StringTokenizer}, however it offers much more control and flexibility including * implementing the {@code ListIterator} interface. By default, it is set up like {@code StringTokenizer}. *
* The input String is split into a number of tokens. Each token is separated from the next String by a * delimiter. One or more delimiter characters must be specified. *
* Each token may be surrounded by quotes. The quote matcher specifies the quote character(s). A quote may be * escaped within a quoted section by duplicating itself. *
* Between each token and the delimiter are potentially characters that need trimming. The trimmer matcher * specifies these characters. One usage might be to trim whitespace characters. *
* At any point outside the quotes there might potentially be invalid characters. The ignored matcher specifies * these characters to be removed. One usage might be to remove new line characters. *
* Empty tokens may be removed or returned as null. * *
* "a,b,c" - Three tokens "a","b","c" (comma delimiter) * " a, b , c " - Three tokens "a","b","c" (default CSV processing trims whitespace) * "a, ", b ,", c" - Three tokens "a, " , " b ", ", c" (quoted text untouched) ** *
| Property | *Type | *Default | *
|---|---|---|
| delim | *CharSetMatcher | *{ \t\n\r\f} | *
| quote | *NoneMatcher | *{} | *
| ignore | *NoneMatcher | *{} | *
| emptyTokenAsNull | *boolean | *false | *
| ignoreEmptyTokens | *boolean | *true | *
* You must call a "reset" method to set the string which you want to parse. *
* * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StringTokenizer getCSVInstance() { return getCSVClone(); } /** * Gets a new tokenizer instance which parses Comma Separated Value strings initializing it with the given input. The default for CSV processing will be * trim whitespace from both ends (which can be overridden with the setTrimmer method). * * @param input the text to parse. * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StringTokenizer getCSVInstance(final char[] input) { return getCSVClone().reset(input); } /** * Gets a new tokenizer instance which parses Comma Separated Value strings initializing it with the given input. The default for CSV processing will be * trim whitespace from both ends (which can be overridden with the setTrimmer method). * * @param input the text to parse. * @return a new tokenizer instance which parses Comma Separated Value strings. */ public static StringTokenizer getCSVInstance(final String input) { return getCSVClone().reset(input); } /** * Returns a clone of {@code TSV_TOKENIZER_PROTOTYPE}. * * @return a clone of {@code TSV_TOKENIZER_PROTOTYPE}. */ private static StringTokenizer getTSVClone() { return (StringTokenizer) TSV_TOKENIZER_PROTOTYPE.clone(); } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be * trim whitespace from both ends (which can be overridden with the setTrimmer method). ** You must call a "reset" method to set the string which you want to parse. *
* * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StringTokenizer getTSVInstance() { return getTSVClone(); } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be trim whitespace from both ends (which can * be overridden with the setTrimmer method). * * @param input the string to parse. * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StringTokenizer getTSVInstance(final char[] input) { return getTSVClone().reset(input); } /** * Gets a new tokenizer instance which parses Tab Separated Value strings. The default for CSV processing will be trim whitespace from both ends (which can * be overridden with the setTrimmer method). * * @param input the string to parse. * @return a new tokenizer instance which parses Tab Separated Value strings. */ public static StringTokenizer getTSVInstance(final String input) { return getTSVClone().reset(input); } /** The text to work on. */ private char[] chars; /** The parsed tokens. */ private String[] tokens; /** The current iteration position. */ private int tokenPos; /** The delimiter matcher. */ private StringMatcher delimMatcher = StringMatcherFactory.INSTANCE.splitMatcher(); /** The quote matcher. */ private StringMatcher quoteMatcher = StringMatcherFactory.INSTANCE.noneMatcher(); /** The ignored matcher. */ private StringMatcher ignoredMatcher = StringMatcherFactory.INSTANCE.noneMatcher(); /** The trimmer matcher. */ private StringMatcher trimmerMatcher = StringMatcherFactory.INSTANCE.noneMatcher(); /** Whether to return empty tokens as null. */ private boolean emptyAsNull; /** Whether to ignore empty tokens. */ private boolean ignoreEmptyTokens = true; /** * Constructs a tokenizer splitting on space, tab, newline and form feed as per StringTokenizer, but with no text to tokenize. ** This constructor is normally used with {@link #reset(String)}. *
*/ public StringTokenizer() { this.chars = null; } /** * Constructs a tokenizer splitting on space, tab, newline and form feed as per StringTokenizer. * * @param input the string which is to be parsed, not cloned. */ public StringTokenizer(final char[] input) { this.chars = input != null ? input.clone() : null; } /** * Constructs a tokenizer splitting on the specified character. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. */ public StringTokenizer(final char[] input, final char delim) { this(input); setDelimiterChar(delim); } /** * Constructs a tokenizer splitting on the specified delimiter character and handling quotes using the specified quote character. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StringTokenizer(final char[] input, final char delim, final char quote) { this(input, delim); setQuoteChar(quote); } /** * Constructs a tokenizer splitting on the specified string. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter string. */ public StringTokenizer(final char[] input, final String delim) { this(input); setDelimiterString(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter matcher. */ public StringTokenizer(final char[] input, final StringMatcher delim) { this(input); setDelimiterMatcher(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher and handling quotes using the specified quote matcher. * * @param input the string which is to be parsed, not cloned. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StringTokenizer(final char[] input, final StringMatcher delim, final StringMatcher quote) { this(input, delim); setQuoteMatcher(quote); } /** * Constructs a tokenizer splitting on space, tab, newline and form feed as per StringTokenizer. * * @param input the string which is to be parsed. */ public StringTokenizer(final String input) { this.chars = input != null ? input.toCharArray() : null; } /** * Constructs a tokenizer splitting on the specified delimiter character. * * @param input the string which is to be parsed. * @param delim the field delimiter character. */ public StringTokenizer(final String input, final char delim) { this(input); setDelimiterChar(delim); } /** * Constructs a tokenizer splitting on the specified delimiter character and handling quotes using the specified quote character. * * @param input the string which is to be parsed. * @param delim the field delimiter character. * @param quote the field quoted string character. */ public StringTokenizer(final String input, final char delim, final char quote) { this(input, delim); setQuoteChar(quote); } /** * Constructs a tokenizer splitting on the specified delimiter string. * * @param input the string which is to be parsed. * @param delim the field delimiter string. */ public StringTokenizer(final String input, final String delim) { this(input); setDelimiterString(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher. * * @param input the string which is to be parsed. * @param delim the field delimiter matcher. */ public StringTokenizer(final String input, final StringMatcher delim) { this(input); setDelimiterMatcher(delim); } /** * Constructs a tokenizer splitting using the specified delimiter matcher and handling quotes using the specified quote matcher. * * @param input the string which is to be parsed. * @param delim the field delimiter matcher. * @param quote the field quoted string matcher. */ public StringTokenizer(final String input, final StringMatcher delim, final StringMatcher quote) { this(input, delim); setQuoteMatcher(quote); } /** * Unsupported ListIterator operation. * * @param obj this parameter ignored. * @throws UnsupportedOperationException always. */ @Override public void add(final String obj) { throw new UnsupportedOperationException("add() is unsupported"); } /** * Adds a token to a list, paying attention to the parameters we've set. * * @param list the list to add to. * @param tok the token to add. */ private void addToken(final List* 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. */ public StringMatcher getIgnoredMatcher() { return ignoredMatcher; } /** * Gets the quote matcher currently in use. ** 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. */ public StringMatcher getQuoteMatcher() { return quoteMatcher; } /** * Gets a copy of the full token list as an independent modifiable array. * * @return The tokens as a String array. */ public String[] getTokenArray() { checkTokenized(); return tokens.clone(); } /** * Gets a copy of the full token list as an independent modifiable list. * * @return The tokens as a String list. */ public List* 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. */ public StringMatcher getTrimmerMatcher() { return trimmerMatcher; } /** * Tests whether there are any more tokens. * * @return true if there are more tokens. */ @Override public boolean hasNext() { checkTokenized(); return tokenPos < tokens.length; } /** * Tests whether there are any previous tokens that can be iterated to. * * @return true if there are previous tokens. */ @Override public boolean hasPrevious() { checkTokenized(); return tokenPos > 0; } /** * Tests whether the tokenizer currently returns empty tokens as null. The default for this property is false. * * @return true if empty tokens are returned as null. */ public boolean isEmptyTokenAsNull() { return this.emptyAsNull; } /** * Tests whether the tokenizer currently ignores empty tokens. The default for this property is true. * * @return true if empty tokens are not returned. */ public boolean isIgnoreEmptyTokens() { return ignoreEmptyTokens; } /** * Tests if the characters at the index specified match the quote already matched in readNextToken(). * * @param srcChars the character array being tokenized. * @param pos the position to check for a quote. * @param len the length of the character array being tokenized. * @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 true if a quote is matched. */ private boolean isQuote(final char[] srcChars, final int pos, final int len, final int quoteStart, final int quoteLen) { for (int i = 0; i < quoteLen; i++) { if (pos + i >= len || srcChars[pos + i] != srcChars[quoteStart + i]) { return false; } } return true; } /** * Gets the next token. * * @return The next String token. * @throws NoSuchElementException if there are no more elements. */ @Override public String next() { if (hasNext()) { return tokens[tokenPos++]; } throw new NoSuchElementException(); } /** * Gets the index of the next token to return. * * @return The next token index. */ @Override public int nextIndex() { return tokenPos; } /** * 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. */ public String nextToken() { if (hasNext()) { return tokens[tokenPos++]; } return null; } /** * Gets the token previous to the last returned token. * * @return The previous token. */ @Override public String previous() { if (hasPrevious()) { return tokens[--tokenPos]; } throw new NoSuchElementException(); } /** * Gets the index of the previous token. * * @return The previous token index. */ @Override public int previousIndex() { return tokenPos - 1; } /** * Gets the previous token from the String. * * @return The previous sequential token, or null when no more tokens are found. */ public String previousToken() { if (hasPrevious()) { return tokens[--tokenPos]; } return null; } /** * Reads character by character through the String to get the next token. * * @param srcChars the character array being tokenized. * @param start the first character of field. * @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 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, final List* This method allows the same tokenizer to be reused for the same String. *
* * @return {@code this} instance. */ public StringTokenizer reset() { tokenPos = 0; tokens = null; return this; } /** * Resets this tokenizer, giving it a new input string to parse. In this manner you can re-use a tokenizer with the same settings on multiple input lines. * * @param input the new character array to tokenize, not cloned, null sets no text to parse. * @return {@code this} instance. */ public StringTokenizer reset(final char[] input) { reset(); this.chars = input != null ? input.clone() : null; return this; } /** * Resets this tokenizer, giving it a new input string to parse. In this manner you can re-use a tokenizer with the same settings on multiple input lines. * * @param input the new string to tokenize, null sets no text to parse. * @return {@code this} instance. */ public StringTokenizer reset(final String input) { reset(); this.chars = input != null ? input.toCharArray() : null; return this; } /** * Throws {@link UnsupportedOperationException} for this unsupported ListIterator operation. * * @param obj this parameter ignored. * @throws UnsupportedOperationException always. */ @Override public void set(final String obj) { throw new UnsupportedOperationException("set() is unsupported"); } /** * Sets the field delimiter character. * * @param delim the delimiter character to use. * @return {@code this} instance. */ public StringTokenizer setDelimiterChar(final char delim) { return setDelimiterMatcher(StringMatcherFactory.INSTANCE.charMatcher(delim)); } /** * Sets the field delimiter matcher. ** The delimiter is used to separate one token from another. *
* * @param delim the delimiter matcher to use. * @return {@code this} instance. */ public StringTokenizer setDelimiterMatcher(final StringMatcher delim) { this.delimMatcher = delim == null ? StringMatcherFactory.INSTANCE.noneMatcher() : delim; return this; } /** * Sets the field delimiter string. * * @param delim the delimiter string to use. * @return {@code this} instance. */ public StringTokenizer setDelimiterString(final String delim) { return setDelimiterMatcher(StringMatcherFactory.INSTANCE.stringMatcher(delim)); } /** * Sets whether the tokenizer should return empty tokens as null. The default for this property is false. * * @param emptyAsNull whether empty tokens are returned as null. * @return {@code this} instance. */ public StringTokenizer setEmptyTokenAsNull(final boolean emptyAsNull) { this.emptyAsNull = emptyAsNull; return this; } /** * Sets the character to ignore. ** This character is ignored when parsing the String, unless it is within a quoted region. *
* * @param ignored the ignored character to use. * @return {@code this} instance. */ public StringTokenizer setIgnoredChar(final char ignored) { return setIgnoredMatcher(StringMatcherFactory.INSTANCE.charMatcher(ignored)); } /** * Sets the matcher for characters to ignore. ** These characters are ignored when parsing the String, unless they are within a quoted region. *
* * @param ignored the ignored matcher to use, null ignored. * @return {@code this} instance. */ public StringTokenizer setIgnoredMatcher(final StringMatcher ignored) { if (ignored != null) { this.ignoredMatcher = ignored; } return this; } /** * Sets whether the tokenizer should ignore and not return empty tokens. The default for this property is true. * * @param ignoreEmptyTokens whether empty tokens are not returned. * @return {@code this} instance. */ public StringTokenizer setIgnoreEmptyTokens(final boolean ignoreEmptyTokens) { this.ignoreEmptyTokens = ignoreEmptyTokens; return this; } /** * Sets the quote character to use. ** The quote character is used to wrap data between the tokens. This enables delimiters to be entered as data. *
* * @param quote the quote character to use. * @return {@code this} instance. */ public StringTokenizer setQuoteChar(final char quote) { return setQuoteMatcher(StringMatcherFactory.INSTANCE.charMatcher(quote)); } /** * Sets the quote matcher to use. ** The quote character is used to wrap data between the tokens. This enables delimiters to be entered as data. *
* * @param quote the quote matcher to use, null ignored. * @return {@code this} instance. */ public StringTokenizer setQuoteMatcher(final StringMatcher quote) { if (quote != null) { this.quoteMatcher = quote; } return this; } /** * Sets the matcher for characters to trim. ** These characters are trimmed off on each side of the delimiter until the token or quote is found. * * @param trimmer the trimmer matcher to use, null ignored. * @return {@code this} instance. */ public StringTokenizer setTrimmerMatcher(final StringMatcher trimmer) { if (trimmer != null) { this.trimmerMatcher = trimmer; } return this; } /** * Gets the number of tokens found in the String. * * @return The number of matched tokens. */ public int size() { checkTokenized(); return tokens.length; } /** * Internal method to performs the tokenization. *
* Most users of this class do not need to call this method. This method will be called automatically by other (public) methods when required. *
** This method exists to allow subclasses to add code before or after the tokenization. For example, a subclass could alter the character array, offset or * count to be parsed, or call the tokenizer multiple times on multiple strings. It is also be possible to filter the results. *
** {@code StrTokenizer} will always pass a zero offset and a count equal to the length of the array to this method, however a subclass may pass other * values, or even an entirely different array. *
* * @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. */ protected List* {@code TextRandomProvider} is a functional interface and need not be explicitly implemented. *
** For example: *
*
* {@code
* UniformRandomProvider rng = RandomSource.create(...);
* RandomStringGenerator gen = RandomStringGenerator.builder()
* .usingRandom(rng::nextInt)
* // additional builder calls as needed
* .build();
* }
*
* @since 1.1
*/
public interface TextRandomProvider extends IntUnaryOperator {
/**
* Generates an int value between 0 (inclusive) and the specified value (exclusive).
*
* @param max Bound on the random number to be returned. Must be positive.
* @return a random int value between 0 (inclusive) and max (exclusive).
* @since 1.14.0
*/
@Override
default int applyAsInt(final int max) {
return nextInt(max);
}
/**
* Generates an int value between 0 (inclusive) and the specified value (exclusive).
*
* @param max Bound on the random number to be returned. Must be positive.
* @return a random int value between 0 (inclusive) and max (exclusive).
* @deprecated Use {@link #applyAsInt(int)}.
*/
@Deprecated
int nextInt(int max);
}
commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/TextStringBuilder.java 0000664 0000000 0000000 00000336204 15114327406 0033051 0 ustar 00root root 0000000 0000000 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.text;
import java.io.IOException;
import java.io.Reader;
import java.io.Serializable;
import java.io.Writer;
import java.nio.CharBuffer;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import java.util.Objects;
import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.text.matcher.StringMatcher;
/**
* Builds a string from constituent parts providing a more flexible and powerful API than {@link StringBuffer} and
* {@link StringBuilder}.
* * The main differences from StringBuffer/StringBuilder are: *
** The aim has been to provide an API that mimics very closely what StringBuffer provides, but with additional methods. * It should be noted that some edge cases, with invalid indices or null input, have been altered - see individual * methods. The biggest of these changes is that by default, null will not output the text 'null'. This can be * controlled by a property, {@link #setNullText(String)}. *
** This class is called {@code TextStringBuilder} instead of {@code StringBuilder} to avoid clashing with * {@link StringBuilder}. *
* * @since 1.3 */ public class TextStringBuilder implements CharSequence, Appendable, Serializable, BuilderThis is set to the same size used in the JDK {@link java.util.ArrayList}:
** Some VMs reserve some header words in an array. * Attempts to allocate larger arrays may result in * OutOfMemoryError: Requested array size exceeds VM limit. **/ private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8; /** * Creates a positive capacity at least as large the minimum required capacity. * If the minimum capacity is negative then this throws an OutOfMemoryError as no array * can be allocated. * * @param minCapacity the minimum capacity * @return the capacity * @throws OutOfMemoryError if the {@code minCapacity} is negative */ private static int createPositiveCapacity(final int minCapacity) { if (minCapacity < 0) { // overflow throw new OutOfMemoryError("Unable to allocate array size: " + Integer.toUnsignedString(minCapacity)); } // This is called when we require buffer expansion to a very big array. // Use the conservative maximum buffer size if possible, otherwise the biggest required. // // Note: In this situation JDK 1.8 java.util.ArrayList returns Integer.MAX_VALUE. // This excludes some VMs that can exceed MAX_BUFFER_SIZE but not allocate a full // Integer.MAX_VALUE length array. // The result is that we may have to allocate an array of this size more than once if // the capacity must be expanded again. return Math.max(minCapacity, MAX_BUFFER_SIZE); } /** * Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this * instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to * be initialized without copying the input array. * * @param initialBuffer The initial array that will back the new builder. * @return A new instance. * @since 1.9 */ public static TextStringBuilder wrap(final char[] initialBuffer) { Objects.requireNonNull(initialBuffer, "initialBuffer"); return new TextStringBuilder(initialBuffer, initialBuffer.length); } /** * Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this * instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to * be initialized without copying the input array. * * @param initialBuffer The initial array that will back the new builder. * @param length The length of the subarray to be used; must be non-negative and no larger than * {@code initialBuffer.length}. The new builder's size will be set to {@code length}. * @return A new instance. * @since 1.9 */ public static TextStringBuilder wrap(final char[] initialBuffer, final int length) { return new TextStringBuilder(initialBuffer, length); } /** Internal data storage. */ private char[] buffer; /** * The new line, {@code null} means use the system default from {@link System#lineSeparator()}. */ private String newLine; /** The null text. */ private String nullText; /** Incremented when the buffer is reallocated. */ private int reallocations; /** Current size of the buffer. */ private int size; /** * Constructs an empty builder with an initial capacity of 32 characters. */ public TextStringBuilder() { this(CAPACITY); } /** * Constructs an instance from a reference to a character array. * * @param initialBuffer a reference to a character array, must not be null. * @param length The length of the subarray to be used; must be non-negative and no larger than {@code initialBuffer.length}. The new builder's size * will be set to {@code length}. * @throws NullPointerException If {@code initialBuffer} is null. * @throws IllegalArgumentException if {@code length} is bad. */ private TextStringBuilder(final char[] initialBuffer, final int length) { this.buffer = Objects.requireNonNull(initialBuffer, "initialBuffer"); if (length < 0 || length > initialBuffer.length) { throw new IllegalArgumentException("initialBuffer.length=" + initialBuffer.length + ", length=" + length); } this.size = length; } /** * Constructs an instance from a character sequence, allocating 32 extra characters for growth. * * @param seq the string to copy, null treated as blank string. * @since 1.9 */ public TextStringBuilder(final CharSequence seq) { this(StringUtils.length(seq) + CAPACITY); if (seq != null) { append(seq); } } /** * Constructs an instance with the specified initial capacity. * * @param initialCapacity the initial capacity, zero or less will be converted to 32. */ public TextStringBuilder(final int initialCapacity) { buffer = new char[initialCapacity <= 0 ? CAPACITY : initialCapacity]; } /** * Constructs an instance from a string, allocating 32 extra characters for growth. * * @param str the string to copy, null treated as blank string. */ public TextStringBuilder(final String str) { this(StringUtils.length(str) + CAPACITY); if (str != null) { append(str); } } /** * Appends a boolean value to the string builder. * * @param value the value to append. * @return {@code this} instance. */ public TextStringBuilder append(final boolean value) { if (value) { ensureCapacityInternal(size + TRUE_STRING_SIZE); appendTrue(size); } else { ensureCapacityInternal(size + FALSE_STRING_SIZE); appendFalse(size); } return this; } /** * Appends a char value to the string builder. * * @param ch the value to append. * @return {@code this} instance. */ @Override public TextStringBuilder append(final char ch) { final int len = length(); ensureCapacityInternal(len + 1); buffer[size++] = ch; return this; } /** * Appends a char array to the string builder. Appending null will call {@link #appendNull()}. * * @param chars the char array to append. * @return {@code this} instance. */ public TextStringBuilder append(final char[] chars) { if (chars == null) { return appendNull(); } final int strLen = chars.length; if (strLen > 0) { final int len = length(); ensureCapacityInternal(len + strLen); System.arraycopy(chars, 0, buffer, len, strLen); size += strLen; } return this; } /** * Appends a char array to the string builder. Appending null will call {@link #appendNull()}. * * @param chars the char array to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. * @throws StringIndexOutOfBoundsException if {@code startIndex} is not in the range {@code 0 <= startIndex <= chars.length}. * @throws StringIndexOutOfBoundsException if {@code length < 0}. * @throws StringIndexOutOfBoundsException if {@code startIndex + length > chars.length}. */ public TextStringBuilder append(final char[] chars, final int startIndex, final int length) { if (chars == null) { return appendNull(); } if (startIndex < 0 || startIndex > chars.length) { throw new StringIndexOutOfBoundsException("Invalid startIndex: " + length); } if (length < 0 || startIndex + length > chars.length) { throw new StringIndexOutOfBoundsException("Invalid length: " + length); } if (length > 0) { final int len = length(); ensureCapacityInternal(len + length); System.arraycopy(chars, startIndex, buffer, len, length); size += length; } return this; } /** * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}. * * @param str the char buffer to append. * @return {@code this} instance. */ public TextStringBuilder append(final CharBuffer str) { return append(str, 0, StringUtils.length(str)); } /** * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}. * * @param buf the char buffer to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. */ public TextStringBuilder append(final CharBuffer buf, final int startIndex, final int length) { if (buf == null) { return appendNull(); } if (buf.hasArray()) { final int totalLength = buf.remaining(); if (startIndex < 0 || startIndex > totalLength) { throw new StringIndexOutOfBoundsException("startIndex must be valid"); } if (length < 0 || startIndex + length > totalLength) { throw new StringIndexOutOfBoundsException("length must be valid"); } final int len = length(); ensureCapacityInternal(len + length); System.arraycopy(buf.array(), buf.arrayOffset() + buf.position() + startIndex, buffer, len, length); size += length; } else { append(buf.toString(), startIndex, length); } return this; } /** * Appends a CharSequence to this string builder. Appending null will call {@link #appendNull()}. * * @param seq the CharSequence to append. * @return {@code this} instance. */ @Override public TextStringBuilder append(final CharSequence seq) { if (seq == null) { return appendNull(); } if (seq instanceof TextStringBuilder) { return append((TextStringBuilder) seq); } if (seq instanceof StringBuilder) { return append((StringBuilder) seq); } if (seq instanceof StringBuffer) { return append((StringBuffer) seq); } if (seq instanceof CharBuffer) { return append((CharBuffer) seq); } return append(seq.toString()); } /** * Appends part of a CharSequence to this string builder. Appending null will call {@link #appendNull()}. * * @param seq the CharSequence to append. * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid. * @return {@code this} instance. */ @Override public TextStringBuilder append(final CharSequence seq, final int startIndex, final int endIndex) { if (seq == null) { return appendNull(); } if (endIndex <= 0) { throw new StringIndexOutOfBoundsException("endIndex must be valid"); } if (startIndex >= endIndex) { throw new StringIndexOutOfBoundsException("endIndex must be greater than startIndex"); } return append(seq.toString(), startIndex, endIndex - startIndex); } /** * Appends a double value to the string builder using {@code String.valueOf}. * * @param value the value to append. * @return {@code this} instance. */ public TextStringBuilder append(final double value) { return append(String.valueOf(value)); } /** * Appends a float value to the string builder using {@code String.valueOf}. * * @param value the value to append. * @return {@code this} instance. */ public TextStringBuilder append(final float value) { return append(String.valueOf(value)); } /** * Appends an int value to the string builder using {@code String.valueOf}. * * @param value the value to append. * @return {@code this} instance. */ public TextStringBuilder append(final int value) { return append(String.valueOf(value)); } /** * Appends a long value to the string builder using {@code String.valueOf}. * * @param value the value to append. * @return {@code this} instance. */ public TextStringBuilder append(final long value) { return append(String.valueOf(value)); } /** * Appends an object to this string builder. Appending null will call {@link #appendNull()}. * * @param obj the object to append. * @return {@code this} instance. */ public TextStringBuilder append(final Object obj) { if (obj == null) { return appendNull(); } if (obj instanceof CharSequence) { return append((CharSequence) obj); } return append(obj.toString()); } /** * Appends a string to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string to append. * @return {@code this} instance. */ public TextStringBuilder append(final String str) { return append(str, 0, StringUtils.length(str)); } /** * Appends part of a string to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. * @throws StringIndexOutOfBoundsException if {@code startIndex} is not in the range {@code 0 <= startIndex <= str.length()}. * @throws StringIndexOutOfBoundsException if {@code length < 0}. * @throws StringIndexOutOfBoundsException if {@code startIndex + length > str.length()}. */ public TextStringBuilder append(final String str, final int startIndex, final int length) { if (str == null) { return appendNull(); } if (startIndex < 0 || startIndex > str.length()) { throw new StringIndexOutOfBoundsException("startIndex must be valid"); } if (length < 0 || startIndex + length > str.length()) { throw new StringIndexOutOfBoundsException("length must be valid"); } if (length > 0) { final int len = length(); ensureCapacityInternal(len + length); str.getChars(startIndex, startIndex + length, buffer, len); size += length; } return this; } /** * Calls {@link String#format(String, Object...)} and appends the result. * * @param format the format string. * @param objs the objects to use in the format string. * @return {@code this} to enable chaining. * @see String#format(String, Object...) */ public TextStringBuilder append(final String format, final Object... objs) { return append(String.format(format, objs)); } /** * Appends a string buffer to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string buffer to append. * @return {@code this} instance. */ public TextStringBuilder append(final StringBuffer str) { return append(str, 0, StringUtils.length(str)); } /** * Appends part of a string buffer to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. */ public TextStringBuilder append(final StringBuffer str, final int startIndex, final int length) { if (str == null) { return appendNull(); } if (startIndex < 0 || startIndex > str.length()) { throw new StringIndexOutOfBoundsException("startIndex must be valid"); } if (length < 0 || startIndex + length > str.length()) { throw new StringIndexOutOfBoundsException("length must be valid"); } if (length > 0) { final int len = length(); ensureCapacityInternal(len + length); str.getChars(startIndex, startIndex + length, buffer, len); size += length; } return this; } /** * Appends a StringBuilder to this string builder. Appending null will call {@link #appendNull()}. * * @param str the StringBuilder to append. * @return {@code this} instance. */ public TextStringBuilder append(final StringBuilder str) { return append(str, 0, StringUtils.length(str)); } /** * Appends part of a StringBuilder to this string builder. Appending null will call {@link #appendNull()}. * * @param str the StringBuilder to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. */ public TextStringBuilder append(final StringBuilder str, final int startIndex, final int length) { if (str == null) { return appendNull(); } if (startIndex < 0 || startIndex > str.length()) { throw new StringIndexOutOfBoundsException("startIndex must be valid"); } if (length < 0 || startIndex + length > str.length()) { throw new StringIndexOutOfBoundsException("length must be valid"); } if (length > 0) { final int len = length(); ensureCapacityInternal(len + length); str.getChars(startIndex, startIndex + length, buffer, len); size += length; } return this; } /** * Appends another string builder to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string builder to append. * @return {@code this} instance. */ public TextStringBuilder append(final TextStringBuilder str) { return append(str, 0, StringUtils.length(str)); } /** * Appends part of a string builder to this string builder. Appending null will call {@link #appendNull()}. * * @param str the string to append. * @param startIndex the start index, inclusive, must be valid. * @param length the length to append, must be valid. * @return {@code this} instance. */ public TextStringBuilder append(final TextStringBuilder str, final int startIndex, final int length) { if (str == null) { return appendNull(); } if (startIndex < 0 || startIndex > str.length()) { throw new StringIndexOutOfBoundsException("startIndex must be valid"); } if (length < 0 || startIndex + length > str.length()) { throw new StringIndexOutOfBoundsException("length must be valid"); } if (length > 0) { final int len = length(); ensureCapacityInternal(len + length); str.getChars(startIndex, startIndex + length, buffer, len); size += length; } return this; } /** * Appends each item in an iterable to the builder without any separators. Appending a null iterable will have no effect. Each object is appended using * {@link #append(Object)}. * * @param iterable the iterable to append. * @return {@code this} instance. */ public TextStringBuilder appendAll(final Iterable iterable) { if (iterable != null) { iterable.forEach(this::append); } return this; } /** * Appends each item in an iterator to the builder without any separators. Appending a null iterator will have no effect. Each object is appended using * {@link #append(Object)}. * * @param it the iterator to append. * @return {@code this} instance. */ public TextStringBuilder appendAll(final Iterator it) { if (it != null) { it.forEachRemaining(this::append); } return this; } /** * Appends each item in an array to the builder without any separators. Appending a null array will have no effect. Each object is appended using * {@link #append(Object)}. * * @param
* By default, the new line is the system default from {@link System#lineSeparator()}. *
** The new line string can be changed using {@link #setNewLineText(String)}. For example, you can use this to force the output to always use Unix line * endings even when on Windows. *
* * @return {@code this} instance. * @see #getNewLineText() * @see #setNewLineText(String) */ public TextStringBuilder appendNewLine() { return append(newLine == null ? System.lineSeparator() : newLine); } /** * Appends the text representing {@code null} to this string builder. * * @return {@code this} instance. */ public TextStringBuilder appendNull() { return nullText != null ? append(nullText) : this; } /** * Appends the pad character to the builder the specified number of times. * * @param length the length to append, negative means no append. * @param padChar the character to append. * @return {@code this} instance. */ public TextStringBuilder appendPadding(final int length, final char padChar) { if (length >= 0) { ensureCapacityInternal(size + length); for (int i = 0; i < length; i++) { buffer[size++] = padChar; } } return this; } /** * Appends a separator if the builder is currently non-empty. The separator is appended using {@link #append(char)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (Iterator it = list.iterator(); it.hasNext();) {
* appendSeparator(',');
* append(it.next());
* }
*
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use. * @return {@code this} instance. */ public TextStringBuilder appendSeparator(final char separator) { return isEmpty() ? this : append(separator); } /** * Appends one of both separators to the builder If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append the * standard-separator ** The separator is appended using {@link #append(char)}. *
* * @param standard the separator if builder is not empty. * @param defaultIfEmpty the separator if builder is empty. * @return {@code this} instance. */ public TextStringBuilder appendSeparator(final char standard, final char defaultIfEmpty) { return append(isEmpty() ? defaultIfEmpty : standard); } /** * Appends a separator to the builder if the loop index is greater than zero. The separator is appended using * {@link #append(char)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (int i = 0; i < list.size(); i++) {
* appendSeparator(",", i);
* append(list.get(i));
* }
*
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use. * @param loopIndex the loop index. * @return {@code this} instance. */ public TextStringBuilder appendSeparator(final char separator, final int loopIndex) { return loopIndex > 0 ? append(separator) : this; } /** * Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The * separator is appended using {@link #append(String)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (Iterator it = list.iterator(); it.hasNext();) {
* appendSeparator(",");
* append(it.next());
* }
*
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public TextStringBuilder appendSeparator(final String separator) { return appendSeparator(separator, null); } /** * Appends a separator to the builder if the loop index is greater than zero. Appending a null separator will have * no effect. The separator is appended using {@link #append(String)}. ** This method is useful for adding a separator each time around the loop except the first. *
* *
* for (int i = 0; i < list.size(); i++) {
* appendSeparator(",", i);
* append(list.get(i));
* }
*
*
* * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}. *
* * @param separator the separator to use, null means no separator. * @param loopIndex the loop index. * @return {@code this} instance. */ public TextStringBuilder appendSeparator(final String separator, final int loopIndex) { return separator != null && loopIndex > 0 ? append(separator) : this; } /** * Appends one of both separators to the StrBuilder. If the builder is currently empty, it will append the * defaultIfEmpty-separator, otherwise it will append the standard-separator. ** Appending a null separator will have no effect. The separator is appended using {@link #append(String)}. *
** This method is for example useful for constructing queries *
* *
* StrBuilder whereClause = new StrBuilder();
* if (searchCommand.getPriority() != null) {
* whereClause.appendSeparator(" and", " where");
* whereClause.append(" priority = ?")
* }
* if (searchCommand.getComponent() != null) {
* whereClause.appendSeparator(" and", " where");
* whereClause.append(" component = ?")
* }
* selectClause.append(whereClause)
*
*
* @param standard the separator if builder is not empty, null means no separator.
* @param defaultIfEmpty the separator if builder is empty, null means no separator.
* @return {@code this} instance.
*/
public TextStringBuilder appendSeparator(final String standard, final String defaultIfEmpty) {
final String str = isEmpty() ? defaultIfEmpty : standard;
return str != null ? append(str) : this;
}
/**
* Appends current contents of this {@code StrBuilder} to the provided {@link Appendable}.
* * This method tries to avoid doing any extra copies of contents. *
* * @param appendable the appendable to append data to. * @throws IOException if an I/O error occurs. * @see #readFrom(Readable) */ public void appendTo(final Appendable appendable) throws IOException { if (appendable instanceof Writer) { ((Writer) appendable).write(buffer, 0, size); } else if (appendable instanceof StringBuilder) { ((StringBuilder) appendable).append(buffer, 0, size); } else if (appendable instanceof StringBuffer) { ((StringBuffer) appendable).append(buffer, 0, size); } else if (appendable instanceof CharBuffer) { ((CharBuffer) appendable).put(buffer, 0, size); } else { appendable.append(this); } } /** Appends {@code "true"}. */ private void appendTrue(int index) { buffer[index++] = 't'; buffer[index++] = 'r'; buffer[index++] = 'u'; buffer[index] = 'e'; size += TRUE_STRING_SIZE; } /** * Appends an iterable placing separators between each value, but not before the first or after the last. Appending * a null iterable will have no effect. Each object is appended using {@link #append(Object)}. * * @param iterable the iterable to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public TextStringBuilder appendWithSeparators(final Iterable iterable, final String separator) { if (iterable != null) { appendWithSeparators(iterable.iterator(), separator); } return this; } /** * Appends an iterator placing separators between each value, but not before the first or after the last. Appending * a null iterator will have no effect. Each object is appended using {@link #append(Object)}. * * @param it the iterator to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public TextStringBuilder appendWithSeparators(final Iterator it, final String separator) { if (it != null) { final String sep = Objects.toString(separator, StringUtils.EMPTY); while (it.hasNext()) { append(it.next()); if (it.hasNext()) { append(sep); } } } return this; } /** * Appends an array placing separators between each value, but not before the first or after the last. Appending a * null array will have no effect. Each object is appended using {@link #append(Object)}. * * @param array the array to append. * @param separator the separator to use, null means no separator. * @return {@code this} instance. */ public TextStringBuilder appendWithSeparators(final Object[] array, final String separator) { if (array != null && array.length > 0) { final String sep = Objects.toString(separator, StringUtils.EMPTY); append(array[0]); for (int i = 1; i < array.length; i++) { append(sep).append(array[i]); } } return this; } /** * Gets the contents of this builder as a Reader. ** This method allows the contents of the builder to be read using any standard method that expects a Reader. *
** To use, simply create a {@code StrBuilder}, populate it with data, call {@code asReader}, and then read away. *
** The internal character array is shared between the builder and the reader. This allows you to append to the * builder after creating the reader, and the changes will be picked up. Note however, that no synchronization * occurs, so you must perform all operations with the builder and the reader in one thread. *
** The returned reader supports marking, and ignores the flush method. *
* * @return a reader that reads from this builder. */ public Reader asReader() { return new TextStringBuilderReader(); } /** * Creates a tokenizer that can tokenize the contents of this builder. ** This method allows the contents of this builder to be tokenized. The tokenizer will be setup by default to * tokenize on space, tab, newline and form feed (as per StringTokenizer). These values can be changed on the * tokenizer class, before retrieving the tokens. *
** The returned tokenizer is linked to this builder. You may intermix calls to the builder and tokenizer within * certain limits, however there is no synchronization. Once the tokenizer has been used once, it must be * {@link StringTokenizer#reset() reset} to pickup the latest changes in the builder. For example: *
* *
* StrBuilder b = new StrBuilder();
* b.append("a b ");
* StrTokenizer t = b.asTokenizer();
* String[] tokens1 = t.getTokenArray(); // returns a,b
* b.append("c d ");
* String[] tokens2 = t.getTokenArray(); // returns a,b (c and d ignored)
* t.reset(); // reset causes builder changes to be picked up
* String[] tokens3 = t.getTokenArray(); // returns a,b,c,d
*
*
* * In addition to simply intermixing appends and tokenization, you can also call the set methods on the tokenizer to * alter how it tokenizes. Just remember to call reset when you want to pickup builder changes. *
** Calling {@link StringTokenizer#reset(String)} or {@link StringTokenizer#reset(char[])} with a non-null value will * break the link with the builder. *
* * @return a tokenizer that is linked to this builder. */ public StringTokenizer asTokenizer() { return new TextStringBuilderTokenizer(); } /** * Gets this builder as a Writer that can be written to. ** This method allows you to populate the contents of the builder using any standard method that takes a Writer. *
** To use, simply create a {@code StrBuilder}, call {@code asWriter}, and populate away. The data is available at * any time using the methods of the {@code StrBuilder}. *
** The internal character array is shared between the builder and the writer. This allows you to intermix calls that * append to the builder and write using the writer and the changes will be occur correctly. Note however, that no * synchronization occurs, so you must perform all operations with the builder and the writer in one thread. *
** The returned writer ignores the close and flush methods. *
* * @return a writer that populates this builder. */ public Writer asWriter() { return new TextStringBuilderWriter(); } /** * Converts this instance to a String. * * @return This instance as a String. * @see #toString() * @deprecated Use {@link #get()}. */ @Deprecated @Override public String build() { return toString(); } /** * Gets the current size of the internal character array buffer. * * @return The capacity. */ public int capacity() { return buffer.length; } /** * Gets the character at the specified index. * * @param index the index to retrieve, must be valid. * @return The character at the index. * @throws IndexOutOfBoundsException if the index is invalid. * @see #setCharAt(int, char) * @see #deleteCharAt(int) */ @Override public char charAt(final int index) { validateIndex(index); return buffer[index]; } /** * Clears the string builder (convenience Collections API style method). ** This method does not reduce the size of the internal character buffer. To do that, call {@code clear()} followed * by {@link #minimizeCapacity()}. *
** This method is the same as {@link #setLength(int)} called with zero and is provided to match the API of * Collections. *
* * @return {@code this} instance. */ public TextStringBuilder clear() { size = 0; return this; } /** * Tests if the string builder contains the specified char. * * @param ch the character to find. * @return true if the builder contains the character. */ public boolean contains(final char ch) { final char[] thisBuf = buffer; for (int i = 0; i < this.size; i++) { if (thisBuf[i] == ch) { return true; } } return false; } /** * Tests if the string builder contains the specified string. * * @param str the string to find. * @return true if the builder contains the string. */ public boolean contains(final String str) { return indexOf(str, 0) >= 0; } /** * Tests if the string builder contains a string matched using the specified matcher. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to search for * the character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return true if the matcher finds a match in the builder. */ public boolean contains(final StringMatcher matcher) { return indexOf(matcher, 0) >= 0; } /** * Deletes the characters between the two specified indices. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder delete(final int startIndex, final int endIndex) { final int actualEndIndex = validateRange(startIndex, endIndex); final int len = actualEndIndex - startIndex; if (len > 0) { deleteImpl(startIndex, actualEndIndex, len); } return this; } /** * Deletes the character wherever it occurs in the builder. * * @param ch the character to delete. * @return {@code this} instance. */ public TextStringBuilder deleteAll(final char ch) { for (int i = 0; i < size; i++) { if (buffer[i] == ch) { final int start = i; while (++i < size) { if (buffer[i] != ch) { break; } } final int len = i - start; deleteImpl(start, i, len); i -= len; } } return this; } /** * Deletes the string wherever it occurs in the builder. * * @param str the string to delete, null causes no action. * @return {@code this} instance. */ public TextStringBuilder deleteAll(final String str) { final int len = str == null ? 0 : str.length(); if (len > 0) { int index = indexOf(str, 0); while (index >= 0) { deleteImpl(index, index + len, len); index = indexOf(str, index); } } return this; } /** * Deletes all parts of the builder that the matcher matches. ** Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all * occurrences where the character 'a' is followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @return {@code this} instance. */ public TextStringBuilder deleteAll(final StringMatcher matcher) { return replace(matcher, null, 0, size, -1); } /** * Deletes the character at the specified index. * * @param index the index to delete. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. * @see #charAt(int) * @see #setCharAt(int, char) */ public TextStringBuilder deleteCharAt(final int index) { validateIndex(index); deleteImpl(index, index + 1, 1); return this; } /** * Deletes the character wherever it occurs in the builder. * * @param ch the character to delete. * @return {@code this} instance. */ public TextStringBuilder deleteFirst(final char ch) { for (int i = 0; i < size; i++) { if (buffer[i] == ch) { deleteImpl(i, i + 1, 1); break; } } return this; } /** * Deletes the string wherever it occurs in the builder. * * @param str the string to delete, null causes no action. * @return {@code this} instance. */ public TextStringBuilder deleteFirst(final String str) { final int len = str == null ? 0 : str.length(); if (len > 0) { final int index = indexOf(str, 0); if (index >= 0) { deleteImpl(index, index + len, len); } } return this; } /** * Deletes the first match within the builder using the specified matcher. ** Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where * the character 'a' is followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @return {@code this} instance. */ public TextStringBuilder deleteFirst(final StringMatcher matcher) { return replace(matcher, null, 0, size, 1); } /** * Internal method to delete a range without validation. * * @param startIndex the start index, must be valid. * @param endIndex the end index (exclusive), must be valid. * @param len the length, must be valid. * @throws IndexOutOfBoundsException if any index is invalid. */ private void deleteImpl(final int startIndex, final int endIndex, final int len) { System.arraycopy(buffer, endIndex, buffer, startIndex, size - endIndex); size -= len; } /** * Gets the character at the specified index before deleting it. * * @param index the index to retrieve, must be valid * @return The character at the index * @throws IndexOutOfBoundsException if the index is invalid * @since 1.9 * @see #charAt(int) * @see #deleteCharAt(int) */ public char drainChar(final int index) { validateIndex(index); final char c = buffer[index]; deleteCharAt(index); return c; } /** * Drains (copies, then deletes) this character sequence into the specified array. This is equivalent to copying the * characters from this sequence into the target and then deleting those character from this sequence. * * @param startIndex first index to copy, inclusive. * @param endIndex last index to copy, exclusive. * @param target the target array, must not be {@code null}. * @param targetIndex the index to start copying in the target. * @return How many characters where copied (then deleted). If this builder is empty, return {@code 0}. * @since 1.9 */ public int drainChars(final int startIndex, final int endIndex, final char[] target, final int targetIndex) { final int length = endIndex - startIndex; if (isEmpty() || length == 0 || target.length == 0) { return 0; } final int actualLen = Math.min(Math.min(size, length), target.length - targetIndex); getChars(startIndex, actualLen, target, targetIndex); delete(startIndex, actualLen); return actualLen; } /** * Checks whether this builder ends with the specified string. ** Note that this method handles null input quietly, unlike String. *
* * @param str the string to search for, null returns false. * @return true if the builder ends with the string. */ public boolean endsWith(final String str) { if (str == null) { return false; } final int len = str.length(); if (len == 0) { return true; } if (len > size) { return false; } int pos = size - len; for (int i = 0; i < len; i++, pos++) { if (buffer[pos] != str.charAt(i)) { return false; } } return true; } /** * Tests the capacity and ensures that it is at least the size specified. * ** Note: This method can be used to minimise memory reallocations during * repeated addition of values by pre-allocating the character buffer. * The method ignores a negative {@code capacity} argument. *
* * @param capacity the capacity to ensure. * @return {@code this} instance. * @throws OutOfMemoryError if the capacity cannot be allocated. */ public TextStringBuilder ensureCapacity(final int capacity) { if (capacity > 0) { ensureCapacityInternal(capacity); } return this; } /** * Ensures that the buffer is at least the size specified. The {@code capacity} argument * is treated as an unsigned integer. * ** This method will raise an {@link OutOfMemoryError} if the capacity is too large * for an array, or cannot be allocated. *
* * @param capacity the capacity to ensure. * @throws OutOfMemoryError if the capacity cannot be allocated. */ private void ensureCapacityInternal(final int capacity) { // Check for overflow of the current buffer. // Assumes capacity is an unsigned integer up to Integer.MAX_VALUE * 2 // (the largest possible addition of two maximum length arrays). if (capacity - buffer.length > 0) { resizeBuffer(capacity); } } /** * Tests the contents of this builder against another to see if they contain the same character content. * * @param obj the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ @Override public boolean equals(final Object obj) { return obj instanceof TextStringBuilder && equals((TextStringBuilder) obj); } /** * Tests the contents of this builder against another to see if they contain the same character content. * * @param other the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ public boolean equals(final TextStringBuilder other) { if (this == other) { return true; } if (other == null) { return false; } if (this.size != other.size) { return false; } // Be aware not to use Arrays.equals(buffer, other.buffer) for equals() method // as length of the buffers may be different (TEXT-211) final char[] thisBuf = this.buffer; final char[] otherBuf = other.buffer; for (int i = size - 1; i >= 0; i--) { if (thisBuf[i] != otherBuf[i]) { return false; } } return true; } /** * Tests the contents of this builder against another to see if they contain the same character content ignoring * case. * * @param other the object to check, null returns false. * @return true if the builders contain the same characters in the same order. */ public boolean equalsIgnoreCase(final TextStringBuilder other) { if (this == other) { return true; } if (this.size != other.size) { return false; } final char[] thisBuf = this.buffer; final char[] otherBuf = other.buffer; for (int i = size - 1; i >= 0; i--) { final char c1 = thisBuf[i]; final char c2 = otherBuf[i]; if (c1 != c2 && Character.toUpperCase(c1) != Character.toUpperCase(c2)) { return false; } } return true; } /** * Converts this instance to a String. * * @return This instance as a String. * @see #toString() * @since 1.12.0 */ @Override public String get() { return toString(); } /** * Gets a direct reference to internal storage, not for public consumption. */ char[] getBuffer() { return buffer; } /** * Copies this character array into the specified array. * * @param target the target array, null will cause an array to be created. * @return The input array, unless that was null or too small. */ public char[] getChars(char[] target) { final int len = length(); if (target == null || target.length < len) { target = new char[len]; } System.arraycopy(buffer, 0, target, 0, len); return target; } /** * Copies this character array into the specified array. * * @param startIndex first index to copy, inclusive, must be valid. * @param endIndex last index to copy, exclusive, must be valid. * @param target the target array, must not be null or too small. * @param targetIndex the index to start copying in target. * @throws NullPointerException if the array is null. * @throws IndexOutOfBoundsException if any index is invalid. */ public void getChars(final int startIndex, final int endIndex, final char[] target, final int targetIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex < 0 || endIndex > length()) { throw new StringIndexOutOfBoundsException(endIndex); } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException("end < start"); } System.arraycopy(buffer, startIndex, target, targetIndex, endIndex - startIndex); } /** * Gets the text to be appended when a {@link #appendNewLine() new line} is added. * * @return The new line text, {@code null} means use the system default from {@link System#lineSeparator()}. */ public String getNewLineText() { return newLine; } /** * Gets the text to be appended when null is added. * * @return The null text, null means no append. */ public String getNullText() { return nullText; } /** * Gets a suitable hash code for this builder. * * @return a hash code. */ @Override public int hashCode() { // no allocation final char[] buf = buffer; int result = 0; for (int i = 0; i < size; i++) { result = 31 * result + buf[i]; } return result; } /** * 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. */ public int indexOf(final char ch) { return indexOf(ch, 0); } /** * Searches the string builder to find the first reference to the specified char. * * @param ch the character to find. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index of the character, or -1 if not found. */ public int indexOf(final char ch, int startIndex) { startIndex = Math.max(0, startIndex); if (startIndex >= size) { return StringUtils.INDEX_NOT_FOUND; } final char[] thisBuf = buffer; for (int i = startIndex; i < size; i++) { if (thisBuf[i] == ch) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder to find the first reference to the specified string. ** 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. */ public int indexOf(final String str) { return indexOf(str, 0); } /** * Searches the string builder to find the first reference to the specified string starting searching from the given * index. ** Note that a null input string will return -1, whereas the JDK throws an exception. *
* * @param str the string to find, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index of the string, or -1 if not found. */ public int indexOf(final String str, int startIndex) { startIndex = Math.max(0, startIndex); if (str == null || startIndex >= size) { return StringUtils.INDEX_NOT_FOUND; } final int strLen = str.length(); if (strLen == 1) { return indexOf(str.charAt(0), startIndex); } if (strLen == 0) { return startIndex; } if (strLen > size) { return StringUtils.INDEX_NOT_FOUND; } final char[] thisBuf = buffer; final int searchLen = size - strLen + 1; for (int i = startIndex; i < searchLen; i++) { boolean found = true; for (int j = 0; j < strLen && found; j++) { found = str.charAt(j) == thisBuf[i + j]; } if (found) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder using the matcher to find the first match. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the * character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return The first index matched, or -1 if not found. */ public int indexOf(final StringMatcher matcher) { return indexOf(matcher, 0); } /** * Searches the string builder using the matcher to find the first match searching from the given index. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the * character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The first index matched, or -1 if not found. */ public int indexOf(final StringMatcher matcher, int startIndex) { startIndex = Math.max(0, startIndex); if (matcher == null || startIndex >= size) { return StringUtils.INDEX_NOT_FOUND; } final int len = size; final char[] buf = buffer; for (int i = startIndex; i < len; i++) { if (matcher.isMatch(buf, i, startIndex, len) > 0) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final boolean value) { validateRange(index, size); if (value) { ensureCapacityInternal(size + TRUE_STRING_SIZE); System.arraycopy(buffer, index, buffer, index + TRUE_STRING_SIZE, size - index); appendTrue(index); } else { ensureCapacityInternal(size + FALSE_STRING_SIZE); System.arraycopy(buffer, index, buffer, index + FALSE_STRING_SIZE, size - index); appendFalse(index); } return this; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final char value) { validateRange(index, size); ensureCapacityInternal(size + 1); System.arraycopy(buffer, index, buffer, index + 1, size - index); buffer[index] = value; size++; return this; } /** * Inserts the character array into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param chars the char array to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final char[] chars) { validateRange(index, size); if (chars == null) { return insert(index, nullText); } final int len = chars.length; if (len > 0) { ensureCapacityInternal(size + len); System.arraycopy(buffer, index, buffer, index + len, size - index); System.arraycopy(chars, 0, buffer, index, len); size += len; } return this; } /** * Inserts part of the character array into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param chars the char array to insert. * @param offset the offset into the character array to start at, must be valid. * @param length the length of the character array part to copy, must be positive. * @return {@code this} instance. * @throws IndexOutOfBoundsException if any index is invalid. */ public TextStringBuilder insert(final int index, final char[] chars, final int offset, final int length) { validateRange(index, size); if (chars == null) { return insert(index, nullText); } if (offset < 0 || offset > chars.length) { throw new StringIndexOutOfBoundsException("Invalid offset: " + offset); } if (length < 0 || offset + length > chars.length) { throw new StringIndexOutOfBoundsException("Invalid length: " + length); } if (length > 0) { ensureCapacityInternal(size + length); System.arraycopy(buffer, index, buffer, index + length, size - index); System.arraycopy(chars, offset, buffer, index, length); size += length; } return this; } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final double value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final float value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final int value) { return insert(index, String.valueOf(value)); } /** * Inserts the value into this builder. * * @param index the index to add at, must be valid. * @param value the value to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final long value) { return insert(index, String.valueOf(value)); } /** * Inserts the string representation of an object into this builder. Inserting null will use the stored null text * value. * * @param index the index to add at, must be valid. * @param obj the object to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, final Object obj) { return insert(index, Objects.toString(obj, nullText)); } /** * Inserts the string into this builder. Inserting null will use the stored null text value. * * @param index the index to add at, must be valid. * @param str the string to insert. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder insert(final int index, String str) { validateRange(index, size); if (str == null) { str = nullText; } if (str != null) { final int strLen = str.length(); if (strLen > 0) { final int newSize = size + strLen; ensureCapacityInternal(newSize); System.arraycopy(buffer, index, buffer, index + strLen, size - index); size = newSize; str.getChars(0, strLen, buffer, index); } } return this; } /** * Checks is the string builder is empty (convenience Collections API style method). ** This method is the same as checking {@link #length()} and is provided to match the API of Collections. *
* * @return {@code true} if the size is {@code 0}. */ public boolean isEmpty() { return size == 0; } /** * Checks is the string builder is not empty. ** This method is the same as checking {@link #length()}. *
* * @return {@code true} if the size is not {@code 0}. * @since 1.9 */ public boolean isNotEmpty() { return size != 0; } /** * Gets whether the internal buffer has been reallocated. * * @return Whether the internal buffer has been reallocated. * @since 1.9 */ public boolean isReallocated() { return reallocations > 0; } /** * 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. */ public int lastIndexOf(final char ch) { return lastIndexOf(ch, size - 1); } /** * Searches the string builder to find the last reference to the specified char. * * @param ch the character to find. * @param startIndex the index to start at, invalid index rounded to edge. * @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; if (startIndex < 0) { return StringUtils.INDEX_NOT_FOUND; } for (int i = startIndex; i >= 0; i--) { if (buffer[i] == ch) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder to find the last reference to the specified string. ** 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. */ public int lastIndexOf(final String str) { return lastIndexOf(str, size - 1); } /** * Searches the string builder to find the last reference to the specified string starting searching from the given * index. ** Note that a null input string will return -1, whereas the JDK throws an exception. *
* * @param str the string to find, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The last index of the string, or -1 if not found. */ public int lastIndexOf(final String str, int startIndex) { startIndex = startIndex >= size ? size - 1 : startIndex; if (str == null || startIndex < 0) { return StringUtils.INDEX_NOT_FOUND; } final int strLen = str.length(); if (strLen == 0) { return startIndex; } if (strLen > size) { return StringUtils.INDEX_NOT_FOUND; } if (strLen == 1) { return lastIndexOf(str.charAt(0), startIndex); } for (int i = startIndex - strLen + 1; i >= 0; i--) { boolean found = true; for (int j = 0; j < strLen && found; j++) { found = str.charAt(j) == buffer[i + j]; } if (found) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Searches the string builder using the matcher to find the last match. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the * character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @return The last index matched, or -1 if not found. */ public int lastIndexOf(final StringMatcher matcher) { return lastIndexOf(matcher, size); } /** * Searches the string builder using the matcher to find the last match searching from the given index. ** Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the * character 'a' followed by a number. *
* * @param matcher the matcher to use, null returns -1. * @param startIndex the index to start at, invalid index rounded to edge. * @return The last index matched, or -1 if not found. */ public int lastIndexOf(final StringMatcher matcher, int startIndex) { startIndex = startIndex >= size ? size - 1 : startIndex; if (matcher == null || startIndex < 0) { return StringUtils.INDEX_NOT_FOUND; } final char[] buf = buffer; final int endIndex = startIndex + 1; for (int i = startIndex; i >= 0; i--) { if (matcher.isMatch(buf, i, 0, endIndex) > 0) { return i; } } return StringUtils.INDEX_NOT_FOUND; } /** * Extracts the leftmost characters from the string builder without throwing an exception. ** This method extracts the left {@code length} characters from the builder. If this many characters are not * available, the whole builder is returned. Thus the returned string may be shorter than the length requested. *
* * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String leftString(final int length) { if (length <= 0) { return StringUtils.EMPTY; } if (length >= size) { return new String(buffer, 0, size); } return new String(buffer, 0, length); } /** * Gets the length of the string builder. * * @return The length */ @Override public int length() { return size; } /** * Extracts some characters from the middle of the string builder without throwing an exception. ** This method extracts {@code length} characters from the builder at the specified index. If the index is negative * it is treated as zero. If the index is greater than the builder size, it is treated as the builder size. If the * length is negative, the empty string is returned. If insufficient characters are available in the builder, as * much as possible is returned. Thus the returned string may be shorter than the length requested. *
* * @param index the index to start at, negative means zero. * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String midString(int index, final int length) { if (index < 0) { index = 0; } if (length <= 0 || index >= size) { return StringUtils.EMPTY; } if (size <= index + length) { return new String(buffer, index, size - index); } return new String(buffer, index, length); } /** * Minimizes the capacity to the actual length of the string. * * @return {@code this} instance. */ public TextStringBuilder minimizeCapacity() { if (buffer.length > size) { reallocate(size); } return this; } /** * If possible, reads chars from the provided {@link CharBuffer} directly into underlying character buffer without * making extra copies. * * @param charBuffer CharBuffer to read. * @return The number of characters read. * @see #appendTo(Appendable) * @since 1.9 */ public int readFrom(final CharBuffer charBuffer) { final int oldSize = size; final int remaining = charBuffer.remaining(); ensureCapacityInternal(size + remaining); charBuffer.get(buffer, size, remaining); size += remaining; return size - oldSize; } /** * If possible, reads all chars from the provided {@link Readable} directly into underlying character buffer without * making extra copies. * * @param readable object to read from. * @return The number of characters read. * @throws IOException if an I/O error occurs. * @see #appendTo(Appendable) */ public int readFrom(final Readable readable) throws IOException { if (readable instanceof Reader) { return readFrom((Reader) readable); } if (readable instanceof CharBuffer) { return readFrom((CharBuffer) readable); } final int oldSize = size; while (true) { ensureCapacityInternal(size + 1); final CharBuffer buf = CharBuffer.wrap(buffer, size, buffer.length - size); final int read = readable.read(buf); if (read == EOS) { break; } size += read; } return size - oldSize; } /** * If possible, reads all chars from the provided {@link Reader} directly into underlying character buffer without * making extra copies. * * @param reader Reader to read. * @return The number of characters read or -1 if we reached the end of stream. * @throws IOException if an I/O error occurs. * @see #appendTo(Appendable) * @since 1.9 */ public int readFrom(final Reader reader) throws IOException { final int oldSize = size; ensureCapacityInternal(size + 1); int readCount = reader.read(buffer, size, buffer.length - size); if (readCount == EOS) { return EOS; } do { size += readCount; ensureCapacityInternal(size + 1); readCount = reader.read(buffer, size, buffer.length - size); } while (readCount != EOS); return size - oldSize; } /** * If possible, reads {@code count} chars from the provided {@link Reader} directly into underlying character buffer without making extra copies. * * @param reader Reader to read. * @param count The maximum characters to read, a value <= 0 returns 0. * @return The number of characters read. If less than {@code count}, then we've reached the end-of-stream, or -1 if we reached the end of stream. * @throws IOException if an I/O error occurs. * @see #appendTo(Appendable) * @since 1.9 */ public int readFrom(final Reader reader, final int count) throws IOException { if (count <= 0) { return 0; } final int oldSize = size; ensureCapacityInternal(size + count); int target = count; int readCount = reader.read(buffer, size, target); if (readCount == EOS) { return EOS; } do { target -= readCount; size += readCount; readCount = reader.read(buffer, size, target); } while (target > 0 && readCount != EOS); return size - oldSize; } /** * Reallocates the buffer to the new length. * * @param newLength the length of the copy to be returned. */ private void reallocate(final int newLength) { this.buffer = Arrays.copyOf(buffer, newLength); this.reallocations++; } /** * Replaces a portion of the string builder with another string. The length of the inserted string does not have to match the removed length. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @param replaceStr the string to replace with, null means delete range. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid. */ public TextStringBuilder replace(final int startIndex, int endIndex, final String replaceStr) { endIndex = validateRange(startIndex, endIndex); final int insertLen = replaceStr == null ? 0 : replaceStr.length(); replaceImpl(startIndex, endIndex, endIndex - startIndex, replaceStr, insertLen); return this; } /** * Advanced search and replaces within the builder using a matcher. ** Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by * a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the string to replace the match with, null is a delete. * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @param replaceCount the number of times to replace, -1 for replace all. * @return {@code this} instance. * @throws IndexOutOfBoundsException if start index is invalid. */ public TextStringBuilder replace(final StringMatcher matcher, final String replaceStr, final int startIndex, int endIndex, final int replaceCount) { endIndex = validateRange(startIndex, endIndex); return replaceImpl(matcher, replaceStr, startIndex, endIndex, replaceCount); } /** * Replaces the search character with the replace character throughout the builder. * * @param search the search character. * @param replace the replace character. * @return {@code this} instance. */ public TextStringBuilder replaceAll(final char search, final char replace) { if (search != replace) { for (int i = 0; i < size; i++) { if (buffer[i] == search) { buffer[i] = replace; } } } return this; } /** * Replaces the search string with the replace string throughout the builder. * * @param searchStr the search string, null causes no action to occur. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public TextStringBuilder replaceAll(final String searchStr, final String replaceStr) { final int searchLen = searchStr == null ? 0 : searchStr.length(); if (searchLen > 0) { final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); int index = indexOf(searchStr, 0); while (index >= 0) { replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen); index = indexOf(searchStr, index + replaceLen); } } return this; } /** * Replaces all matches within the builder with the replace string. ** Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace all * occurrences where the character 'a' is followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public TextStringBuilder replaceAll(final StringMatcher matcher, final String replaceStr) { return replace(matcher, replaceStr, 0, size, -1); } /** * Replaces the first instance of the search character with the replace character in the builder. * * @param search the search character. * @param replace the replace character. * @return {@code this} instance. */ public TextStringBuilder replaceFirst(final char search, final char replace) { if (search != replace) { for (int i = 0; i < size; i++) { if (buffer[i] == search) { buffer[i] = replace; break; } } } return this; } /** * Replaces the first instance of the search string with the replace string. * * @param searchStr the search string, null causes no action to occur. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public TextStringBuilder replaceFirst(final String searchStr, final String replaceStr) { final int searchLen = searchStr == null ? 0 : searchStr.length(); if (searchLen > 0) { final int index = indexOf(searchStr, 0); if (index >= 0) { final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen); } } return this; } /** * Replaces the first match within the builder with the replace string. ** Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where * the character 'a' is followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the replace string, null is equivalent to an empty string. * @return {@code this} instance. */ public TextStringBuilder replaceFirst(final StringMatcher matcher, final String replaceStr) { return replace(matcher, replaceStr, 0, size, 1); } /** * Internal method to delete a range without validation. * * @param startIndex the start index, must be valid. * @param endIndex the end index (exclusive), must be valid. * @param removeLen the length to remove (endIndex - startIndex), must be valid. * @param insertStr the string to replace with, null means delete range. * @param insertLen the length of the insert string, must be valid. * @throws IndexOutOfBoundsException if any index is invalid. */ private void replaceImpl(final int startIndex, final int endIndex, final int removeLen, final String insertStr, final int insertLen) { final int newSize = size - removeLen + insertLen; if (insertLen != removeLen) { ensureCapacityInternal(newSize); System.arraycopy(buffer, endIndex, buffer, startIndex + insertLen, size - endIndex); size = newSize; } if (insertLen > 0) { insertStr.getChars(0, insertLen, buffer, startIndex); } } /** * Replaces within the builder using a matcher. ** Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all * occurrences where the character 'a' is followed by a number. *
* * @param matcher the matcher to use to find the deletion, null causes no action. * @param replaceStr the string to replace the match with, null is a delete. * @param from the start index, must be valid. * @param to the end index (exclusive), must be valid. * @param replaceCount the number of times to replace, -1 for replace all. * @return {@code this} instance. * @throws IndexOutOfBoundsException if any index is invalid. */ private TextStringBuilder replaceImpl(final StringMatcher matcher, final String replaceStr, final int from, int to, int replaceCount) { if (matcher == null || size == 0) { return this; } final int replaceLen = replaceStr == null ? 0 : replaceStr.length(); for (int i = from; i < to && replaceCount != 0; i++) { final char[] buf = buffer; final int removeLen = matcher.isMatch(buf, i, from, to); if (removeLen > 0) { replaceImpl(i, i + removeLen, removeLen, replaceStr, replaceLen); to = to - removeLen + replaceLen; i = i + replaceLen - 1; if (replaceCount > 0) { replaceCount--; } } } return this; } /** * Resizes the buffer to at least the size specified. * * @param minCapacity the minimum required capacity. * @throws OutOfMemoryError if the {@code minCapacity} is negative. */ private void resizeBuffer(final int minCapacity) { // Overflow-conscious code treats the min and new capacity as unsigned. final int oldCapacity = buffer.length; int newCapacity = oldCapacity * 2; if (Integer.compareUnsigned(newCapacity, minCapacity) < 0) { newCapacity = minCapacity; } if (Integer.compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) { newCapacity = createPositiveCapacity(minCapacity); } reallocate(newCapacity); } /** * Reverses the string builder placing each character in the opposite index. * * @return {@code this} instance. */ public TextStringBuilder reverse() { if (size == 0) { return this; } final int half = size / 2; final char[] buf = buffer; for (int leftIdx = 0, rightIdx = size - 1; leftIdx < half; leftIdx++, rightIdx--) { final char swap = buf[leftIdx]; buf[leftIdx] = buf[rightIdx]; buf[rightIdx] = swap; } return this; } /** * Extracts the rightmost characters from the string builder without throwing an exception. ** This method extracts the right {@code length} characters from the builder. If this many characters are not * available, the whole builder is returned. Thus the returned string may be shorter than the length requested. *
* * @param length the number of characters to extract, negative returns empty string. * @return The new string. */ public String rightString(final int length) { if (length <= 0) { return StringUtils.EMPTY; } if (length >= size) { return new String(buffer, 0, size); } return new String(buffer, size - length, length); } /** * Clears and sets this builder to the given value. * * @param str the new value. * @return {@code this} instance. * @since 1.9 * @see #charAt(int) * @see #deleteCharAt(int) */ public TextStringBuilder set(final CharSequence str) { return clear().append(str); } /** * Sets the character at the specified index. * * @param index the index to set * @param ch the new character * @return {@code this} instance. * @throws IndexOutOfBoundsException if the index is invalid * @see #charAt(int) * @see #deleteCharAt(int) */ public TextStringBuilder setCharAt(final int index, final char ch) { validateIndex(index); buffer[index] = ch; return this; } /** * Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero. * * @param length the length to set to, must be zero or positive. * @return {@code this} instance. * @throws IndexOutOfBoundsException if the length is negative. */ public TextStringBuilder setLength(final int length) { if (length < 0) { throw new StringIndexOutOfBoundsException(length); } if (length < size) { size = length; } else if (length > size) { ensureCapacityInternal(length); final int oldEnd = size; size = length; Arrays.fill(buffer, oldEnd, length, '\0'); } return this; } /** * Sets the text to be appended when {@link #appendNewLine() new line} is called. * * @param newLine the new line text, {@code null} means use the system default from {@link System#lineSeparator()}. * @return {@code this} instance. */ public TextStringBuilder setNewLineText(final String newLine) { this.newLine = newLine; return this; } /** * Sets the text to be appended when null is added. * * @param nullText the null text, null means no append. * @return {@code this} instance. */ public TextStringBuilder setNullText(String nullText) { if (nullText != null && nullText.isEmpty()) { nullText = null; } this.nullText = nullText; return this; } /** * Gets the length of the string builder. ** This method is the same as {@link #length()} and is provided to match the API of Collections. *
* * @return The length. */ public int size() { return size; } /** * Checks whether this builder starts with the specified string. ** Note that this method handles null input quietly, unlike String. *
* * @param str the string to search for, null returns false. * @return true if the builder starts with the string. */ public boolean startsWith(final String str) { if (str == null) { return false; } final int len = str.length(); if (len == 0) { return true; } if (len > size) { return false; } for (int i = 0; i < len; i++) { if (buffer[i] != str.charAt(i)) { return false; } } return true; } /** * {@inheritDoc} */ @Override public CharSequence subSequence(final int startIndex, final int endIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex > size) { throw new StringIndexOutOfBoundsException(endIndex); } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException(endIndex - startIndex); } return substring(startIndex, endIndex); } /** * Extracts a portion of this string builder as a string. * * @param start the start index, inclusive, must be valid. * @return The new string. * @throws IndexOutOfBoundsException if the index is invalid. */ public String substring(final int start) { return substring(start, size); } /** * Extracts a portion of this string builder as a string. ** Note: This method treats an endIndex greater than the length of the builder as equal to the length of the * builder, and continues without error, unlike StringBuffer or String. *
* * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return The new string. * @throws IndexOutOfBoundsException if the index is invalid. */ public String substring(final int startIndex, int endIndex) { endIndex = validateRange(startIndex, endIndex); return new String(buffer, startIndex, endIndex - startIndex); } /** * Copies the builder's character array into a new character array. * * @return a new array that represents the contents of the builder. */ public char[] toCharArray() { return size == 0 ? ArrayUtils.EMPTY_CHAR_ARRAY : Arrays.copyOf(buffer, size); } /** * Copies part of the builder's character array into a new character array. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return a new array that holds part of the contents of the builder. * @throws IndexOutOfBoundsException if startIndex is invalid, or if endIndex is invalid (but endIndex greater than size is valid). */ public char[] toCharArray(final int startIndex, int endIndex) { endIndex = validateRange(startIndex, endIndex); final int len = endIndex - startIndex; return len == 0 ? ArrayUtils.EMPTY_CHAR_ARRAY : Arrays.copyOfRange(buffer, startIndex, endIndex); } /** * Gets a String version of the string builder, creating a new instance each time the method is called. ** Note that unlike StringBuffer, the string version returned is independent of the string builder. *
* * @return The builder as a String. */ @Override public String toString() { return new String(buffer, 0, size); } /** * Gets a StringBuffer version of the string builder, creating a new instance each time the method is called. * * @return The builder as a StringBuffer. */ public StringBuffer toStringBuffer() { return new StringBuffer(size).append(buffer, 0, size); } /** * Gets a StringBuilder version of the string builder, creating a new instance each time the method is called. * * @return The builder as a StringBuilder. */ public StringBuilder toStringBuilder() { return new StringBuilder(size).append(buffer, 0, size); } /** * Trims the builder by removing characters less than or equal to a space from the beginning and end. * * @return {@code this} instance. */ public TextStringBuilder trim() { if (size == 0) { return this; } int len = size; final char[] buf = buffer; int pos = 0; while (pos < len && buf[pos] <= SPACE) { pos++; } while (pos < len && buf[len - 1] <= SPACE) { len--; } if (len < size) { delete(len, size); } if (pos > 0) { delete(0, pos); } return this; } /** * Validates that an index is in the range {@code 0 <= index < size}. * * @param index the index to test. * @throws IndexOutOfBoundsException Thrown when the index is not the range {@code 0 <= index < size}. */ protected void validateIndex(final int index) { if (index < 0 || index >= size) { throw new StringIndexOutOfBoundsException(index); } } /** * Validates parameters defining a range of the builder. * * @param startIndex the start index, inclusive, must be valid. * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string. * @return A valid end index. * @throws StringIndexOutOfBoundsException if the index is invalid. */ protected int validateRange(final int startIndex, int endIndex) { if (startIndex < 0) { throw new StringIndexOutOfBoundsException(startIndex); } if (endIndex > size) { endIndex = size; } if (startIndex > endIndex) { throw new StringIndexOutOfBoundsException("end < start"); } return endIndex; } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/WordUtils.java 0000664 0000000 0000000 00000105556 15114327406 0031367 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text; import java.util.HashSet; import java.util.Set; import java.util.function.Predicate; import java.util.regex.Matcher; import java.util.regex.Pattern; import org.apache.commons.lang3.ArrayUtils; import org.apache.commons.lang3.StringUtils; import org.apache.commons.lang3.Strings; import org.apache.commons.lang3.Validate; /** * Operations on Strings that contain words. * ** This class tries to handle {@code null} input gracefully. An exception will not be thrown for a * {@code null} input. Each method documents its behavior in more detail. *
* * @since 1.1 */ public class WordUtils { /** * Abbreviates the words nicely. * ** This method searches for the first space after the lower limit and abbreviates * the String there. It will also append any String passed as a parameter * to the end of the String. The upper limit can be specified to forcibly * abbreviate a String. *
* * @param str the string to be abbreviated. If null is passed, null is returned. * If the empty String is passed, the empty string is returned. * @param lower the lower limit; negative value is treated as zero. * @param upper the upper limit; specify -1 if no limit is desired. * The upper limit cannot be lower than the lower limit. * @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. * *
* WordUtils.abbreviate("Now is the time for all good men", 0, 40, null)); = "Now"
* WordUtils.abbreviate("Now is the time for all good men", 10, 40, null)); = "Now is the"
* WordUtils.abbreviate("Now is the time for all good men", 20, 40, null)); = "Now is the time for all"
* WordUtils.abbreviate("Now is the time for all good men", 0, 40, "")); = "Now"
* WordUtils.abbreviate("Now is the time for all good men", 10, 40, "")); = "Now is the"
* WordUtils.abbreviate("Now is the time for all good men", 20, 40, "")); = "Now is the time for all"
* WordUtils.abbreviate("Now is the time for all good men", 0, 40, " ...")); = "Now ..."
* WordUtils.abbreviate("Now is the time for all good men", 10, 40, " ...")); = "Now is the ..."
* WordUtils.abbreviate("Now is the time for all good men", 20, 40, " ...")); = "Now is the time for all ..."
* WordUtils.abbreviate("Now is the time for all good men", 0, -1, "")); = "Now"
* WordUtils.abbreviate("Now is the time for all good men", 10, -1, "")); = "Now is the"
* WordUtils.abbreviate("Now is the time for all good men", 20, -1, "")); = "Now is the time for all"
* WordUtils.abbreviate("Now is the time for all good men", 50, -1, "")); = "Now is the time for all good men"
* WordUtils.abbreviate("Now is the time for all good men", 1000, -1, "")); = "Now is the time for all good men"
* WordUtils.abbreviate("Now is the time for all good men", 9, -10, null)); = Throws {@link IllegalArgumentException}
* WordUtils.abbreviate("Now is the time for all good men", 10, 5, null)); = Throws {@link IllegalArgumentException}
*
*/
public static String abbreviate(final String str, int lower, int upper, final String appendToEnd) {
Validate.isTrue(upper >= -1, "upper value cannot be less than -1");
Validate.isTrue(upper >= lower || upper == -1, "upper value is less than lower value");
if (StringUtils.isEmpty(str)) {
return str;
}
// if the lower value is greater than the length of the string,
// set to the length of the string
if (lower > str.length()) {
lower = str.length();
}
// if the upper value is -1 (i.e. no limit) or is greater
// than the length of the string, set to the length of the string
if (upper == -1 || upper > str.length()) {
upper = str.length();
}
final StringBuilder result = new StringBuilder();
final int index = Strings.CS.indexOf(str, " ", lower);
if (index == -1) {
result.append(str, 0, upper);
// only if abbreviation has occurred do we append the appendToEnd value
if (upper != str.length()) {
result.append(StringUtils.defaultString(appendToEnd));
}
} else {
result.append(str, 0, Math.min(index, upper));
result.append(StringUtils.defaultString(appendToEnd));
}
return result.toString();
}
/**
* Capitalizes all the whitespace separated words in a String.
* Only the first character of each word is changed. To convert the
* rest of each word to lowercase at the same time,
* use {@link #capitalizeFully(String)}.
*
* Whitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}. * Capitalization uses the Unicode title case, normally equivalent to * upper case.
* *
* WordUtils.capitalize(null) = null
* WordUtils.capitalize("") = ""
* WordUtils.capitalize("i am FINE") = "I Am FINE"
*
*
* @param str the String to capitalize, may be null.
* @return capitalized String, {@code null} if null String input.
* @see #uncapitalize(String)
* @see #capitalizeFully(String)
*/
public static String capitalize(final String str) {
return capitalize(str, null);
}
/**
* Capitalizes all the delimiter separated words in a String.
* Only the first character of each word is changed. To convert the
* rest of each word to lowercase at the same time,
* use {@link #capitalizeFully(String, char[])}.
*
* The delimiters represent a set of characters understood to separate words. * The first string character and the first non-delimiter character after a * delimiter will be capitalized.
* *A {@code null} input String returns {@code null}. * Capitalization uses the Unicode title case, normally equivalent to * upper case.
* *
* WordUtils.capitalize(null, *) = null
* WordUtils.capitalize("", *) = ""
* WordUtils.capitalize(*, new char[0]) = *
* WordUtils.capitalize("i am fine", null) = "I Am Fine"
* WordUtils.capitalize("i aM.fine", {'.'}) = "I aM.Fine"
* WordUtils.capitalize("i am fine", new char[]{}) = "I am fine"
*
*
* @param str the String to capitalize, may be null.
* @param delimiters set of characters to determine capitalization, null means whitespace.
* @return capitalized String, {@code null} if null String input.
* @see #uncapitalize(String)
* @see #capitalizeFully(String)
*/
public static String capitalize(final String str, final char... delimiters) {
if (StringUtils.isEmpty(str)) {
return str;
}
final PredicateWhitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}. * Capitalization uses the Unicode title case, normally equivalent to * upper case.
* *
* WordUtils.capitalizeFully(null) = null
* WordUtils.capitalizeFully("") = ""
* WordUtils.capitalizeFully("i am FINE") = "I Am Fine"
*
*
* @param str the String to capitalize, may be null.
* @return capitalized String, {@code null} if null String input.
*/
public static String capitalizeFully(final String str) {
return capitalizeFully(str, null);
}
/**
* Converts all the delimiter separated words in a String into capitalized words,
* that is each word is made up of a titlecase character and then a series of
* lowercase characters.
*
* The delimiters represent a set of characters understood to separate words. * The first string character and the first non-delimiter character after a * delimiter will be capitalized.
* *A {@code null} input String returns {@code null}. * Capitalization uses the Unicode title case, normally equivalent to * upper case.
* *
* WordUtils.capitalizeFully(null, *) = null
* WordUtils.capitalizeFully("", *) = ""
* WordUtils.capitalizeFully(*, null) = *
* WordUtils.capitalizeFully(*, new char[0]) = *
* WordUtils.capitalizeFully("i aM.fine", {'.'}) = "I am.Fine"
*
*
* @param str the String to capitalize, may be null.
* @param delimiters set of characters to determine capitalization, null means whitespace.
* @return capitalized String, {@code null} if null String input.
*/
public static String capitalizeFully(String str, final char... delimiters) {
if (StringUtils.isEmpty(str)) {
return str;
}
str = str.toLowerCase();
return capitalize(str, delimiters);
}
/**
* Checks if the String contains all words in the given array.
*
* * A {@code null} String will return {@code false}. A {@code null}, zero * length search array or if one element of array is null will return {@code false}. *
* *
* WordUtils.containsAllWords(null, *) = false
* WordUtils.containsAllWords("", *) = false
* WordUtils.containsAllWords(*, null) = false
* WordUtils.containsAllWords(*, []) = false
* WordUtils.containsAllWords("abcd", "ab", "cd") = false
* WordUtils.containsAllWords("abc def", "def", "abc") = true
*
*
* @param word The CharSequence to check, may be null.
* @param words The array of String words to search for, may be null.
* @return {@code true} if all search words are found, {@code false} otherwise.
*/
public static boolean containsAllWords(final CharSequence word, final CharSequence... words) {
if (StringUtils.isEmpty(word) || ArrayUtils.isEmpty(words)) {
return false;
}
for (final CharSequence w : words) {
if (StringUtils.isBlank(w)) {
return false;
}
final Pattern p = Pattern.compile(".*\\b" + Pattern.quote(w.toString()) + "\\b.*");
if (!p.matcher(word).matches()) {
return false;
}
}
return true;
}
/**
* Given the array of delimiters supplied; returns a function determining whether a character code point is a delimiter.
* The function provides O(1) lookup time.
* Whitespace is defined by {@link Character#isWhitespace(char)} and is used as the defaultvalue if delimiters is null.
*
* @param delimiters set of characters to determine delimiters, null means whitespace.
* @return PredicateAll first characters after whitespace are returned as a new string. * Their case is not changed.
* *Whitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}.
* *
* WordUtils.initials(null) = null
* WordUtils.initials("") = ""
* WordUtils.initials("Ben John Lee") = "BJL"
* WordUtils.initials("Ben J.Lee") = "BJ"
*
*
* @param str the String to get initials from, may be null.
* @return String of initial letters, {@code null} if null String input.
* @see #initials(String,char[])
*/
public static String initials(final String str) {
return initials(str, null);
}
/**
* Extracts the initial characters from each word in the String.
*
* All first characters after the defined delimiters are returned as a new string. * Their case is not changed.
* *If the delimiters array is null, then Whitespace is used. * Whitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}. * An empty delimiter array returns an empty String.
* *
* WordUtils.initials(null, *) = null
* WordUtils.initials("", *) = ""
* WordUtils.initials("Ben John Lee", null) = "BJL"
* WordUtils.initials("Ben J.Lee", null) = "BJ"
* WordUtils.initials("Ben J.Lee", [' ','.']) = "BJL"
* WordUtils.initials(*, new char[0]) = ""
*
*
* @param str the String to get initials from, may be null.
* @param delimiters set of characters to determine words, null means whitespace.
* @return String of initial characters, {@code null} if null String input.
* @see #initials(String)
*/
public static String initials(final String str, final char... delimiters) {
if (StringUtils.isEmpty(str)) {
return str;
}
if (delimiters != null && delimiters.length == 0) {
return StringUtils.EMPTY;
}
final PredicateWhitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}.
* *
* StringUtils.swapCase(null) = null
* StringUtils.swapCase("") = ""
* StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
*
*
* @param str the String to swap case, may be null.
* @return The changed String, {@code null} if null String input.
*/
public static String swapCase(final String str) {
if (StringUtils.isEmpty(str)) {
return str;
}
final int strLen = str.length();
final int[] newCodePoints = new int[strLen];
int outOffset = 0;
boolean whitespace = true;
for (int index = 0; index < strLen;) {
final int oldCodepoint = str.codePointAt(index);
final int newCodePoint;
if (Character.isUpperCase(oldCodepoint) || Character.isTitleCase(oldCodepoint)) {
newCodePoint = Character.toLowerCase(oldCodepoint);
whitespace = false;
} else if (Character.isLowerCase(oldCodepoint)) {
if (whitespace) {
newCodePoint = Character.toTitleCase(oldCodepoint);
whitespace = false;
} else {
newCodePoint = Character.toUpperCase(oldCodepoint);
}
} else {
whitespace = Character.isWhitespace(oldCodepoint);
newCodePoint = oldCodepoint;
}
newCodePoints[outOffset++] = newCodePoint;
index += Character.charCount(newCodePoint);
}
return new String(newCodePoints, 0, outOffset);
}
/**
* Uncapitalizes all the whitespace separated words in a String.
* Only the first character of each word is changed.
*
* Whitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}.
* *
* WordUtils.uncapitalize(null) = null
* WordUtils.uncapitalize("") = ""
* WordUtils.uncapitalize("I Am FINE") = "i am fINE"
*
*
* @param str the String to uncapitalize, may be null.
* @return uncapitalized String, {@code null} if null String input.
* @see #capitalize(String)
*/
public static String uncapitalize(final String str) {
return uncapitalize(str, null);
}
/**
* Uncapitalizes all the whitespace separated words in a String.
* Only the first character of each word is changed.
*
* The delimiters represent a set of characters understood to separate words. * The first string character and the first non-delimiter character after a * delimiter will be uncapitalized.
* *Whitespace is defined by {@link Character#isWhitespace(char)}. * A {@code null} input String returns {@code null}.
* *
* WordUtils.uncapitalize(null, *) = null
* WordUtils.uncapitalize("", *) = ""
* WordUtils.uncapitalize(*, null) = *
* WordUtils.uncapitalize(*, new char[0]) = *
* WordUtils.uncapitalize("I AM.FINE", {'.'}) = "i AM.fINE"
* WordUtils.uncapitalize("I am fine", new char[]{}) = "i am fine"
*
*
* @param str the String to uncapitalize, may be null.
* @param delimiters set of characters to determine uncapitalization, null means whitespace.
* @return uncapitalized String, {@code null} if null String input.
* @see #capitalize(String)
*/
public static String uncapitalize(final String str, final char... delimiters) {
if (StringUtils.isEmpty(str)) {
return str;
}
final PredicateNew lines will be separated by the system property line separator. * Very long words, such as URLs will not be wrapped.
* *Leading spaces on a new line are stripped. * Trailing spaces are not stripped.
* *| input | *wrapLength | *result | *
|---|---|---|
| null | ** | *null | *
| "" | ** | *"" | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *"Here is one line of\ntext that is going\nto be wrapped after\n20 columns." | *
| "Click here to jump to the commons website - https://commons.apache.org" | *20 | *"Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org" | *
| "Click here, https://commons.apache.org, to jump to the commons website" | *20 | *"Click here,\nhttps://commons.apache.org,\nto jump to the\ncommons website" | *
Leading spaces on a new line are stripped. * Trailing spaces are not stripped.
* *| input | *wrapLength | *newLineString | *wrapLongWords | *result | *
|---|---|---|---|---|
| null | ** | ** | *true/false | *null | *
| "" | ** | ** | *true/false | *"" | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *"\n" | *true/false | *"Here is one line of\ntext that is going\nto be wrapped after\n20 columns." | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *"<br />" | *true/false | *"Here is one line of<br />text that is going< * br />to be wrapped after<br />20 columns." | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *null | *true/false | *"Here is one line of" + systemNewLine + "text that is going" * + systemNewLine + "to be wrapped after" + systemNewLine + "20 columns." | *
| "Click here to jump to the commons website - https://commons.apache.org" | *20 | *"\n" | *false | *"Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org" | *
| "Click here to jump to the commons website - https://commons.apache.org" | *20 | *"\n" | *true | *"Click here to jump\nto the commons\nwebsite -\nhttps://commons.apach\ne.org" | *
Leading spaces on a new line are stripped. * Trailing spaces are not stripped.
* *| input | *wrapLength | *newLineString | *wrapLongWords | *wrapOn | *result | *
|---|---|---|---|---|---|
| null | ** | ** | *true/false | ** | *null | *
| "" | ** | ** | *true/false | ** | *"" | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *"\n" | *true/false | *" " | *"Here is one line of\ntext that is going\nto be wrapped after\n20 columns." | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *"<br />" | *true/false | *" " | *"Here is one line of<br />text that is going<br /> * to be wrapped after<br />20 columns." | *
| "Here is one line of text that is going to be wrapped after 20 columns." | *20 | *null | *true/false | *" " | *"Here is one line of" + systemNewLine + "text that is going" * + systemNewLine + "to be wrapped after" + systemNewLine + "20 columns." | *
| "Click here to jump to the commons website - https://commons.apache.org" | *20 | *"\n" | *false | *" " | *"Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org" | *
| "Click here to jump to the commons website - https://commons.apache.org" | *20 | *"\n" | *true | *" " | *"Click here to jump\nto the commons\nwebsite -\nhttps://commons.apach\ne.org" | *
| "flammable/inflammable" | *20 | *"\n" | *true | *"/" | *"flammable\ninflammable" | *
This constructor is public to permit tools that require a JavaBean * instance to operate.
*/ public WordUtils() { } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/diff/ 0000775 0000000 0000000 00000000000 15114327406 0027464 5 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/diff/CommandVisitor.java 0000664 0000000 0000000 00000010206 15114327406 0033264 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text.diff; /** * Walks through {@link EditScript EditScript} objects. ** Users should implement this interface in order to walk through * the {@link EditScript EditScript} object created by the comparison * of two sequences. This is a direct application of the visitor * design pattern. The {@link EditScript#visit EditScript.visit} * method takes an object implementing this interface as an argument, * it will perform the loop over all commands in the script and the * proper methods of the user class will be called as the commands are * encountered. *
** The implementation of the user visitor class will depend on the * need. Here are two examples. *
** The first example is a visitor that build the longest common * subsequence: *
*
* import org.apache.commons.text.diff.CommandVisitor;
*
* import java.util.ArrayList;
*
* public class LongestCommonSubSequence implements CommandVisitor {
*
* public LongestCommonSubSequence() {
* a = new ArrayList();
* }
*
* public void visitInsertCommand(Object object) {
* }
*
* public void visitKeepCommand(Object object) {
* a.add(object);
* }
*
* public void visitDeleteCommand(Object object) {
* }
*
* public Object[] getSubSequence() {
* return a.toArray();
* }
*
* private ArrayList a;
*
* }
*
* * The second example is a visitor that shows the commands and the way * they transform the first sequence into the second one: *
*
* import org.apache.commons.text.diff.CommandVisitor;
*
* import java.util.Arrays;
* import java.util.ArrayList;
* import java.util.Iterator;
*
* public class ShowVisitor implements CommandVisitor {
*
* public ShowVisitor(Object[] sequence1) {
* v = new ArrayList();
* v.addAll(Arrays.asList(sequence1));
* index = 0;
* }
*
* public void visitInsertCommand(Object object) {
* v.insertElementAt(object, index++);
* display("insert", object);
* }
*
* public void visitKeepCommand(Object object) {
* ++index;
* display("keep ", object);
* }
*
* public void visitDeleteCommand(Object object) {
* v.remove(index);
* display("delete", object);
* }
*
* private void display(String commandName, Object object) {
* System.out.println(commandName + " " + object + ": " + this);
* }
*
* public String toString() {
* StringBuffer buffer = new StringBuffer();
* for (Iterator iter = v.iterator(); iter.hasNext();) {
* buffer.append(' ').append(iter.next());
* }
* return buffer.toString();
* }
*
* private ArrayList v;
* private int index;
*
* }
*
*
* @param * When one object of the first sequence has no corresponding object in the * second sequence at the right place, the {@link EditScript edit script} * transforming the first sequence into the second sequence uses an instance of * this class to represent the deletion of this object. The objects embedded in * these type of commands always come from the first sequence. *
* * @see StringsComparator * @see EditScript * @param* When two objects sequences are compared through the * {@link StringsComparator#getScript StringsComparator.getScript} method, * the result is provided has a {@link EditScript script} containing the commands * that progressively transform the first sequence into the second one. *
** There are only three types of commands, all of which are subclasses of this * abstract class. Each command is associated with one object belonging to at * least one of the sequences. These commands are {@link InsertCommand * InsertCommand} which correspond to an object of the second sequence being * inserted into the first sequence, {@link DeleteCommand DeleteCommand} which * correspond to an object of the first sequence being removed and * {@link KeepCommand KeepCommand} which correspond to an object of the first * sequence which {@code equals} an object in the second sequence. It is * guaranteed that comparison is always performed this way (i.e. the * {@code equals} method of the object from the first sequence is used and * the object passed as an argument comes from the second sequence) ; this can * be important if subclassing is used for some elements in the first sequence * and the {@code equals} method is specialized. *
* ** This code has been adapted from Apache Commons Collections 4.0. *
* * @see StringsComparator * @see EditScript * @param* This method is invoked for each commands belonging to an {@link EditScript EditScript}, in order to implement the visitor design pattern *
* * @param visitor the visitor to be accepted. */ public abstract void accept(CommandVisitor* An edit script is the most general view of the differences between two * sequences. It is built as the result of the comparison between two sequences * by the {@link StringsComparator StringsComparator} class. The user can * walk through it using the visitor design pattern. *
** It is guaranteed that the objects embedded in the {@link InsertCommand insert * commands} come from the second sequence and that the objects embedded in * either the {@link DeleteCommand delete commands} or {@link KeepCommand keep * commands} come from the first sequence. This can be important if subclassing * is used for some elements in the first sequence and the {@code equals} * method is specialized. *
* * @see StringsComparator * @see EditCommand * @see CommandVisitor * @see ReplacementsHandler * @param* When one object of the second sequence has no corresponding object in the * first sequence at the right place, the {@link EditScript edit script} * transforming the first sequence into the second sequence uses an instance of * this class to represent the insertion of this object. The objects embedded in * these type of commands always come from the second sequence. *
* * @see StringsComparator * @see EditScript * @param* When one object of the first sequence {@code equals} another objects in * the second sequence at the right place, the {@link EditScript edit script} * transforming the first sequence into the second sequence uses an instance of * this class to represent the keeping of this object. The objects embedded in * these type of commands always come from the first sequence. *
* * @see StringsComparator * @see EditScript * @param* The comparison of two objects sequences leads to the identification of common * parts and parts which only belong to the first or to the second sequence. The * common parts appear in the edit script in the form of keep commands, * they can be considered as synchronization objects between the two sequences. * These synchronization objects split the two sequences in synchronized * sub-sequences. The first sequence can be transformed into the second one by * replacing each synchronized sub-sequence of the first sequence by the * corresponding sub-sequence of the second sequence. This is a synthetic way to * see an {@link EditScript edit script}, replacing individual * {@link DeleteCommand delete}, {@link KeepCommand keep} and * {@link InsertCommand insert} commands by fewer replacements acting on * complete sub-sequences. *
** This class is devoted to perform this interpretation. It visits an * {@link EditScript edit script} (because it implements the * {@link CommandVisitor CommandVisitor} interface) and calls a user-supplied * handler implementing the {@link ReplacementsHandler ReplacementsHandler} * interface to process the sub-sequences. *
* * @see ReplacementsHandler * @see EditScript * @see StringsComparator * @param* When a synchronization object is identified, the pending insertions and pending deletions sets are provided to the user handler as subsequences. *
* * @param object synchronization object detected. */ @Override public void visitKeepCommand(final T object) { if (pendingDeletions.isEmpty() && pendingInsertions.isEmpty()) { ++skipped; } else { handler.handleReplacement(skipped, pendingDeletions, pendingInsertions); pendingDeletions.clear(); pendingInsertions.clear(); skipped = 1; } } } ReplacementsHandler.java 0000664 0000000 0000000 00000004203 15114327406 0034167 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/diff /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.text.diff; import java.util.List; /** * Handles synchronized replacement sequences. * * @param* This method is called by a {@link ReplacementsFinder ReplacementsFinder} instance when it has synchronized two sub-sequences of object arrays being * compared, and at least one of the sequences is non-empty. Since the sequences are synchronized, the objects before the two sub-sequences are equals (if * they exist). This property also holds for the objects after the two sub-sequences. *
** The replacement is defined as replacing the {@code from} sub-sequence into the {@code to} sub-sequence. *
* * @param skipped number of tokens skipped since the last call (i.e. number of tokens that were in both sequences), this number should be strictly positive * except on the very first call where it can be zero (if the first object of the two sequences are different). * @param from sub-sequence of objects coming from the first sequence. * @param to sub-sequence of objects coming from the second sequence. */ void handleReplacement(int skipped, List* It is guaranteed that the comparisons will always be done as * {@code o1.equals(o2)} where {@code o1} belongs to the first * sequence and {@code o2} belongs to the second sequence. This can * be important if subclassing is used for some elements in the first * sequence and the {@code equals} method is specialized. *
** Comparison can be seen from two points of view: either as giving the smallest * modification allowing to transform the first sequence into the second one, or * as giving the longest sequence which is a subsequence of both initial * sequences. The {@code equals} method is used to compare objects, so any * object can be put into sequences. Modifications include deleting, inserting * or keeping one object, starting from the beginning of the first sequence. *
** This class implements the comparison algorithm, which is the very efficient * algorithm from Eugene W. Myers * * An O(ND) Difference Algorithm and Its Variations. This algorithm produces * the shortest possible {@link EditScript edit script} containing all the * {@link EditCommand commands} needed to transform the first sequence into * the second one. * *
* This code has been adapted from Apache Commons Collections 4.0. *
* * @see EditScript * @see EditCommand * @see CommandVisitor * @since 1.0 */ public class StringsComparator { /** * Holds the end part of a path under construction in a {@link StringsComparator StringsComparator}. */ private static final class Snake { /** Start index. */ private final int start; /** End index. */ private final int end; /** Diagonal number. */ private final int diag; /** * Constructs a new instance of Snake with specified indices. * * @param start start index of the snake. * @param end end index of the snake. * @param diag diagonal number. */ Snake(final int start, final int end, final int diag) { this.start = start; this.end = end; this.diag = diag; } /** * Gets the diagonal number of the snake. * * @return diagonal number of the snake. */ public int getDiag() { return diag; } /** * Gets the end index of the snake. * * @return end index of the snake. */ public int getEnd() { return end; } /** * Gets the start index of the snake. * * @return start index of the snake. */ public int getStart() { return start; } } /** * First character sequence. */ private final String left; /** * Second character sequence. */ private final String right; /** * Temporary array. */ private final int[] vDown; /** * Temporary array. */ private final int[] vUp; /** * Constructs a new instance of StringsComparator. ** It is guaranteed that the comparisons will always be done as {@code o1.equals(o2)} where {@code o1} belongs to the first sequence and {@code o2} * belongs to the second sequence. This can be important if subclassing is used for some elements in the first sequence and the {@code equals} method is * specialized. *
* * @param left first character sequence to be compared. * @param right second character sequence to be compared. */ public StringsComparator(final String left, final String right) { this.left = left; this.right = right; final int size = left.length() + right.length() + 2; vDown = new int[size]; vUp = new int[size]; } /** * Builds an edit script. * * @param start1 the begin of the first sequence to be compared. * @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. * @param script the edited script. */ private void buildScript(final int start1, final int end1, final int start2, final int end2, final EditScript* The snake is found using the MYERS Algorithm (this algorithms has also been implemented in the GNU diff program). This algorithm is explained in Eugene * Myers article: An O(ND) Difference Algorithm and Its Variations. *
* * @param start1 the begin of the first sequence to be compared. * @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. */ private Snake getMiddleSnake(final int start1, final int end1, final int start2, final int end2) { // Myers Algorithm // Initializations final int m = end1 - start1; final int n = end2 - start2; if (m == 0 || n == 0) { return null; } final int delta = m - n; final int sum = n + m; final int offset = (sum % 2 == 0 ? sum : sum + 1) / 2; vDown[1 + offset] = start1; vUp[1 + offset] = end1 + 1; for (int d = 0; d <= offset; ++d) { // Down for (int k = -d; k <= d; k += 2) { // First step final int i = k + offset; if (k == -d || k != d && vDown[i - 1] < vDown[i + 1]) { vDown[i] = vDown[i + 1]; } else { vDown[i] = vDown[i - 1] + 1; } int x = vDown[i]; int y = x - start1 + start2 - k; while (x < end1 && y < end2 && left.charAt(x) == right.charAt(y)) { vDown[i] = ++x; ++y; } // Second step if (delta % 2 != 0 && delta - d <= k && k <= delta + d && vUp[i - delta] <= vDown[i]) { // NOPMD return buildSnake(vUp[i - delta], k + start1 - start2, end1, end2); } } // Up for (int k = delta - d; k <= delta + d; k += 2) { // First step final int i = k + offset - delta; if (k == delta - d || k != delta + d && vUp[i + 1] <= vUp[i - 1]) { vUp[i] = vUp[i + 1] - 1; } else { vUp[i] = vUp[i - 1]; } int x = vUp[i] - 1; int y = x - start1 + start2 - k; while (x >= start1 && y >= start2 && left.charAt(x) == right.charAt(y)) { vUp[i] = x--; y--; } // Second step if (delta % 2 == 0 && -d <= k && k <= d && vUp[i] <= vDown[i + delta]) { // NOPMD return buildSnake(vUp[i], k + start1 - start2, end1, end2); } } } // this should not happen throw new IllegalStateException("Internal Error"); } /** * Gets the {@link EditScript} object. ** It is guaranteed that the objects embedded in the {@link InsertCommand insert commands} come from the second sequence and that the objects embedded in * either the {@link DeleteCommand delete commands} or {@link KeepCommand keep commands} come from the first sequence. This can be important if subclassing * is used for some elements in the first sequence and the {@code equals} method is specialized. *
* * @return The edit script resulting from the comparison of the two sequences. */ public EditScriptProvides algorithms for diff between strings.
* *The initial implementation of the Myers algorithm was adapted from the * commons-collections sequence package.
* * @since 1.0 */ package org.apache.commons.text.diff; commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/doc-files/ 0000775 0000000 0000000 00000000000 15114327406 0030421 5 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/doc-files/leaf.svg 0000664 0000000 0000000 00000011536 15114327406 0032057 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/doc-files/logo.png 0000664 0000000 0000000 00000022356 15114327406 0032077 0 ustar 00root root 0000000 0000000 ‰PNG IHDR ý d M\6w sRGBÙÉ, gAMA ± üa cHRM z& €„ ú €è u0 ê` :˜ pœºQ< bKGD ÿ ÿ ÿ ½§“ pHYs .# .#x¥?v tIMEé }^÷ IDATxÚíyœ EÙÇ¿Õ3{d áH$ $Ù ÛIHÈ¡È)Š/Èá QxEŠ'(Çv ؽAEQ+€ ^ˆ x rˆ€Ó$°›ž › „„’@H²»³»ÓõþQ5log®ÝÍEý>Ÿù|fzºº««úWõ* Using this Reader avoids reading a whole file into memory as a {@code String} to perform string substitution, for * example, when a Servlet filters a file to a client. *
** This class is not thread-safe. *
* * @since 1.9 */ public class StringSubstitutorReader extends FilterReader { /** The end-of-stream character marker. */ private static final int EOS = -1; /** Our internal buffer. */ private final TextStringBuilder buffer = new TextStringBuilder(); /** End-of-Stream flag. */ private boolean eos; /** Matches escaped variable starts. */ private final StringMatcher prefixEscapeMatcher; /** Internal buffer for {@link #read()} method. */ private final char[] read1CharBuffer = {0}; /** The underlying StringSubstitutor. */ private final StringSubstitutor stringSubstitutor; /** We don't always want to drain the whole buffer. */ private int toDrain; /** * Constructs a new instance. * * @param reader the underlying reader containing the template text known to the given {@code StringSubstitutor}. * @param stringSubstitutor How to replace as we read. * @throws NullPointerException if {@code reader} is {@code null}. * @throws NullPointerException if {@code stringSubstitutor} is {@code null}. */ public StringSubstitutorReader(final Reader reader, final StringSubstitutor stringSubstitutor) { super(reader); this.stringSubstitutor = new StringSubstitutor(stringSubstitutor); this.prefixEscapeMatcher = StringMatcherFactory.INSTANCE.charMatcher(stringSubstitutor.getEscapeChar()) .andThen(stringSubstitutor.getVariablePrefixMatcher()); } /** * Buffers the requested number of characters if available. */ private int buffer(final int requestReadCount) throws IOException { final int actualReadCount = buffer.readFrom(super.in, requestReadCount); eos = actualReadCount == EOS; return actualReadCount; } /** * Reads a requested number of chars from the underlying reader into the buffer. On EOS, set the state is DRAINING, * drain, and return a drain count, otherwise, returns the actual read count. */ private int bufferOrDrainOnEos(final int requestReadCount, final char[] target, final int targetIndex, final int targetLength) throws IOException { final int actualReadCount = buffer(requestReadCount); return drainOnEos(actualReadCount, target, targetIndex, targetLength); } /** * Drains characters from our buffer to the given {@code target}. */ private int drain(final char[] target, final int targetIndex, final int targetLength) { final int actualLen = Math.min(buffer.length(), targetLength); final int drainCount = buffer.drainChars(0, actualLen, target, targetIndex); toDrain -= drainCount; if (buffer.isEmpty() || toDrain == 0) { // nothing or everything drained. toDrain = 0; } return drainCount; } /** * Drains from the buffer to the target only if we are at EOS per the input count. If input count is EOS, drain and * returns the drain count, otherwise return the input count. If draining, the state is set to DRAINING. */ private int drainOnEos(final int readCountOrEos, final char[] target, final int targetIndex, final int targetLength) { if (readCountOrEos == EOS) { // At EOS, drain. if (buffer.isNotEmpty()) { toDrain = buffer.size(); return drain(target, targetIndex, targetLength); } return EOS; } return readCountOrEos; } /** * Tests if our buffer matches the given string matcher at the given position in the buffer. */ private boolean isBufferMatchAt(final StringMatcher stringMatcher, final int pos) { return stringMatcher.isMatch(buffer, pos) == stringMatcher.size(); } /** * Tests if we are draining. */ private boolean isDraining() { return toDrain > 0; } /** * Reads a single character. * * @return a character as an {@code int} or {@code -1} for end-of-stream. * @throws IOException If an I/O error occurs. */ @Override public int read() throws IOException { int count = 0; // ask until we get a char or EOS do { count = read(read1CharBuffer, 0, 1); if (count == EOS) { return EOS; } // keep on buffering } while (count < 1); return read1CharBuffer[0]; } /** * Reads characters into a portion of an array. * * @param target Target buffer. * @param targetIndexIn Index in the target at which to start storing characters. * @param targetLengthIn Maximum number of characters to read. * @return The number of characters read, or -1 on end of stream. * @throws IOException If an I/O error occurs. */ @Override public int read(final char[] target, final int targetIndexIn, final int targetLengthIn) throws IOException { // The whole thing is inefficient because we must look for a balanced suffix to match the starting prefix // Trying to substitute an incomplete expression can perform replacements when it should not. // At a high level: // - if draining, drain until empty or target length hit // - copy to target until we find a variable start // - buffer until a balanced suffix is read, then substitute. if (eos && buffer.isEmpty()) { return EOS; } if (targetLengthIn <= 0) { // short-circuit: ask nothing, give nothing return 0; } // drain check int targetIndex = targetIndexIn; int targetLength = targetLengthIn; if (isDraining()) { // drain as much as possible final int drainCount = drain(target, targetIndex, Math.min(toDrain, targetLength)); if (drainCount == targetLength) { // drained length requested, target is full, can only do more in the next invocation return targetLength; } // drained less than requested, target not full. targetIndex += drainCount; targetLength -= drainCount; } // BUFFER from the underlying reader final int minReadLenPrefix = prefixEscapeMatcher.size(); // READ enough to test for an [optionally escaped] variable start int readCount = buffer(readCount(minReadLenPrefix, 0)); if (buffer.length() < minReadLenPrefix && targetLength < minReadLenPrefix) { // read less than minReadLenPrefix, no variable possible final int drainCount = drain(target, targetIndex, targetLength); targetIndex += drainCount; final int targetSize = targetIndex - targetIndexIn; return eos && targetSize <= 0 ? EOS : targetSize; } if (eos) { // EOS stringSubstitutor.replaceIn(buffer); toDrain = buffer.size(); final int drainCount = drain(target, targetIndex, targetLength); targetIndex += drainCount; final int targetSize = targetIndex - targetIndexIn; return eos && targetSize <= 0 ? EOS : targetSize; } // PREFIX // buffer and drain until we find a variable start, escaped or plain. int balance = 0; final StringMatcher prefixMatcher = stringSubstitutor.getVariablePrefixMatcher(); int pos = 0; while (targetLength > 0) { if (isBufferMatchAt(prefixMatcher, 0)) { balance = 1; pos = prefixMatcher.size(); break; } if (isBufferMatchAt(prefixEscapeMatcher, 0)) { balance = 1; pos = prefixEscapeMatcher.size(); break; } // drain first char final int drainCount = drain(target, targetIndex, 1); targetIndex += drainCount; targetLength -= drainCount; if (buffer.size() < minReadLenPrefix) { readCount = bufferOrDrainOnEos(minReadLenPrefix, target, targetIndex, targetLength); if (eos || isDraining()) { // if draining, readCount is a drain count if (readCount != EOS) { targetIndex += readCount; targetLength -= readCount; } final int actual = targetIndex - targetIndexIn; return actual > 0 ? actual : EOS; } } } // we found a variable start if (targetLength <= 0) { // no more room in target return targetLengthIn; } // SUFFIX // buffer more to find a balanced suffix final StringMatcher suffixMatcher = stringSubstitutor.getVariableSuffixMatcher(); final int minReadLenSuffix = Math.max(minReadLenPrefix, suffixMatcher.size()); readCount = buffer(readCount(minReadLenSuffix, pos)); if (eos) { // EOS stringSubstitutor.replaceIn(buffer); toDrain = buffer.size(); final int drainCount = drain(target, targetIndex, targetLength); return targetIndex + drainCount - targetIndexIn; } // buffer and break out when we find the end or a balanced suffix while (true) { if (isBufferMatchAt(suffixMatcher, pos)) { balance--; pos++; if (balance == 0) { break; } } else if (isBufferMatchAt(prefixMatcher, pos)) { balance++; pos += prefixMatcher.size(); } else if (isBufferMatchAt(prefixEscapeMatcher, pos)) { balance++; pos += prefixEscapeMatcher.size(); } else { pos++; } readCount = buffer(readCount(minReadLenSuffix, pos)); if (readCount == EOS && pos >= buffer.size()) { break; } } // substitute final int endPos = pos + 1; final int leftover = Math.max(0, buffer.size() - pos); stringSubstitutor.replaceIn(buffer, 0, Math.min(buffer.size(), endPos)); pos = buffer.size() - leftover; final int drainLen = Math.min(targetLength, pos); // only drain up to what we've substituted toDrain = pos; drain(target, targetIndex, drainLen); return targetIndex - targetIndexIn + drainLen; } /** * Returns how many chars to attempt reading to have room in the buffer for {@code count} chars starting at position * {@code pos}. */ private int readCount(final int count, final int pos) { final int avail = buffer.size() - pos; return avail >= count ? 0 : count - avail; } } commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/io/package-info.java 0000664 0000000 0000000 00000002404 15114327406 0032352 0 ustar 00root root 0000000 0000000 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** ** {@link org.apache.commons.text.io.StringSubstitutorReader} is a {@link java.io.Reader} that performs string * substitution on a source {@code Reader} using a {@link org.apache.commons.text.StringSubstitutor}. *
* ** Using this Reader avoids reading a whole file into memory as a {@code String} to perform string substitution, for * example, when a Servlet filters a file to a client. *
* * @since 1.9 */ package org.apache.commons.text.io; commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup/ 0000775 0000000 0000000 00000000000 15114327406 0030065 5 ustar 00root root 0000000 0000000 AbstractPathFencedLookup.java 0000664 0000000 0000000 00000003311 15114327406 0035526 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache license, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the license for the specific language governing permissions and * limitations under the license. */ package org.apache.commons.text.lookup; import java.nio.file.Path; /** * Abstracts string lookup that guards Path lookups with a fence. */ abstract class AbstractPathFencedLookup extends AbstractStringLookup { /** * A fence is made of Paths guarding Path resolution. */ protected final PathFence fence; /** * Constructs a new instance. * * @param paths The fences guarding Path resolution. */ AbstractPathFencedLookup(final Path... paths) { this.fence = PathFence.builder().setRoots(paths).get(); } /** * Gets a Path for the given file name checking that it resolves within our fence. * * @param fileName the file name to resolve. * @return a fenced Path. * @throws IllegalArgumentException if the file name is not without our fence. */ protected Path getPath(final String fileName) { return fence.apply(fileName); } } AbstractStringLookup.java 0000664 0000000 0000000 00000005710 15114327406 0035000 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache license, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the license for the specific language governing permissions and * limitations under the license. */ package org.apache.commons.text.lookup; import org.apache.commons.lang3.StringUtils; /** * A default lookup for others to extend in this package. * * @since 1.3 */ abstract class AbstractStringLookup implements StringLookup { /** * The default split char. */ protected static final char SPLIT_CH = ':'; /** * The default split string. */ protected static final String SPLIT_STR = String.valueOf(SPLIT_CH); /** * Creates a lookup key for a given file and key. */ static String toLookupKey(final String left, final String right) { return toLookupKey(left, SPLIT_STR, right); } /** * Creates a lookup key for a given file and key. */ static String toLookupKey(final String left, final String separator, final String right) { return left + separator + right; } /** * Returns the substring after the first occurrence of {@code ch} in {@code value}. * * @param value The source string. * @param ch The character to search. * @return a new string. * @deprecated Use {@link StringUtils#substringAfter(String, int)}. */ @Deprecated protected String substringAfter(final String value, final char ch) { return StringUtils.substringAfter(value, ch); } /** * Returns the substring after the first occurrence of {@code str} in {@code value}. * * @param value The source string. * @param str The string to search. * @return a new string. * @deprecated Use {@link StringUtils#substringAfter(String, String)}. */ @Deprecated protected String substringAfter(final String value, final String str) { return StringUtils.substringAfter(value, str); } /** * Returns the substring after the first occurrence of {@code ch} in {@code value}. * * @param value The source string. * @param ch The character to search. * @return a new string. * @deprecated Use {@link StringUtils#substringAfterLast(String, int)}. */ @Deprecated protected String substringAfterLast(final String value, final char ch) { return StringUtils.substringAfterLast(value, ch); } } BiFunctionStringLookup.java 0000664 0000000 0000000 00000006730 15114327406 0035300 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache license, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the license for the specific language governing permissions and * limitations under the license. */ package org.apache.commons.text.lookup; import java.util.Map; import java.util.Objects; import java.util.function.BiFunction; /** * A function-based lookup where the request for a lookup is answered by applying that function with a key. ** Public access is through {@link StringLookupFactory}. *
* * @param A function's second input type
* @see StringLookupFactory
* @since 1.9
*/
final class BiFunctionStringLookup {
/**
* Creates a new instance backed by a Function.
*
* @param
* If the function is null, then null is returned. The function result object is converted to a string using
* toString().
*
* This class represents the simplest form of a string to string map. It has a benefit over a map in that it can create
* the result on demand based on the key.
*
* For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the value
* on demand from the database.
*
* Like {@link BiFunction} is a variant of {@link Function}, this {@code BiStringLookup} is a variant of
* {@link StringLookup}.
*
* The internal implementation may use any mechanism to return the value. The simplest implementation is to use a
* Map. However, virtually any implementation is possible.
*
* For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the
* value on demand from the database Or, a numeric based implementation could be created that treats the key as an
* integer, increments the value and return the result as a string - converting 1 to 2, 15 to 16 etc.
*
* This method always returns a String, regardless of the underlying data, by converting it as necessary. For
* example:
*
* Looks up the value of a fully-qualified static final value.
*
* 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. static final) member field. Then the class is loaded and the field's
* value is obtained using reflection.
*
* 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.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The above examples convert {@code java.awt.event.KeyEvent.VK_ESCAPE} to {@code "27"}.
*
* This class was adapted from Apache Commons Configuration.
*
* Public access is through {@link StringLookupFactory}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The above examples convert {@code "yyyy-MM-dd"} to today's date, for example, {@code "2019-08-04"}.
*
* Public access is through {@link StringLookupFactory}.
*
* This enum was adapted and expanded from Apache Commons Configuration 2.4.
* NOTE: Starting in version 1.10.0, not all lookups defined in this class are
* included by default in the
* {@link StringLookupFactory#addDefaultStringLookups(java.util.Map) StringLookupFactory.addDefaultStringLookups}
* method. See the {@link StringLookupFactory} class documentation for details.
*
* The lookup keys are:
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The above examples convert {@code "address|apache.org"} to {@code "95.216.24.32} (or {@code "40.79.78.1"}).
*
* Public access is through {@link StringLookupFactory}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* The above example converts {@code "UTF-8:com/domain/document.properties"} to the UTF-8 contents of the file at {@code com/domain/document.properties}.
*
* Using a {@link StringSubstitutor}:
*
* The above example converts {@code "UTF-8:SomePath"} to the UTF-8 contents of the file at {@code SomePath}.
*
* Public access is through {@link StringLookupFactory}.
*
* For example: "UTF-8:com/domain/document.properties".
*
* Public access is through {@link StringLookupFactory}.
*
* If the function is null, then null is returned. The function result object is converted to a string using
* toString().
*
* Public access is through {@link StringLookupFactory}.
*
* The lookup keys are:
*
* Public access is through {@link StringLookupFactory}.
*
* Uses the {@link StringLookupFactory default lookups}.
*
* Public access is through {@link StringLookupFactory}.
*
* Uses the {@link StringLookupFactory default lookups}.
*
* Uses the {@link StringLookupFactory default lookups}.
*
* The lookup keys with examples are:
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The above examples convert {@code "version"} to the current VM version, for example,
* {@code "Java version 1.8.0_181"}.
*
* Public access is through {@link StringLookupFactory}.
*
* The lookup keys with examples are:
*
* Looks up the value for a given key in the format "Document::Key".
*
* Note the use of "::" instead of ":" to allow for "C:" drive letters in paths.
*
* For example: "com/domain/document.properties:key".
*
* Public access is through {@link StringLookupFactory}.
*
* For example: "com/domain/document.xml::/path/to/node".
*
* Note the use of "::" instead of ":" to allow for "C:" drive letters in paths.
*
* Looks up the value for a given key in the format "BundleName:BundleKey".
*
* For example: "com.domain.messages:MyKey".
*
* Public access is through {@link StringLookupFactory}.
*
* Execute the script with the engine name in the format "EngineName:Script".
*
* For example: {@code "javascript:3 + 4"}.
*
* Using a {@link StringSubstitutor}:
*
* Public access is through {@link StringLookupFactory}.
*
* For example: {@code "javascript:3 + 4"}.
*
* This class represents the simplest form of a string to string map. It has a benefit over a map in that it can create
* the result on demand based on the key.
*
* For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the value
* on demand from the database.
*
* The internal implementation may use any mechanism to return the value. The simplest implementation is to use a
* Map. However, virtually any implementation is possible.
*
* For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the
* value on demand from the database Or, a numeric based implementation could be created that treats the key as an
* integer, increments the value and return the result as a string - converting 1 to 2, 15 to 16 etc.
*
* This method always returns a String, regardless of the underlying data, by converting it as necessary. For
* example:
*
* The internal implementation may use any mechanism to return the value. The simplest implementation is to use a
* Map. However, virtually any implementation is possible.
*
* For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the
* value on demand from the database Or, a numeric based implementation could be created that treats the key as an
* integer, increments the value and return the result as a string - converting 1 to 2, 15 to 16 etc.
*
* This method always returns a String, regardless of the underlying data, by converting it as necessary. For
* example:
*
* The "classic" look up is {@link #mapStringLookup(Map)}.
*
* The methods for variable interpolation (A.K.A. variable substitution) are:
*
* Unless explicitly requested otherwise, a set of default lookups are included for convenience with these variable interpolation methods. These defaults are
* listed in the table below. However, the exact lookups included can be configured through the use of the {@value #DEFAULT_STRING_LOOKUPS_PROPERTY} system
* property. If present, this system property will be parsed as a comma-separated list of lookup names, with the names being those defined by the
* {@link DefaultStringLookup} enum. For example, setting this system property to {@code "BASE64_ENCODER,ENVIRONMENT"} will only include the
* {@link DefaultStringLookup#BASE64_ENCODER BASE64_ENCODER} and {@link DefaultStringLookup#ENVIRONMENT ENVIRONMENT} lookups. Setting the property to the empty
* string will cause no defaults to be configured. Note that not all lookups defined here and in {@link DefaultStringLookup} are included by default.
* Specifically, lookups that can execute code (e.g., {@link DefaultStringLookup#SCRIPT SCRIPT}) and those that can result in contact with remote servers (e.g.,
* {@link DefaultStringLookup#URL URL} and {@link DefaultStringLookup#DNS DNS}) are not included by default. The current set of default lookups can be accessed
* directly with {@link #addDefaultStringLookups(Map)}.
*
* This class also provides functional lookups used as building blocks for other lookups.
*
* Path Fences apply to the file, property, and XML string lookups.
*
* The format of the property string is a comma-separated list of names from the {@link DefaultStringLookup} enum.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "HelloWorld!"} to {@code "SGVsbG9Xb3JsZCE="}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert (on Linux) {@code "USER"} to the current user name. On Windows 10, you would use {@code "USERNAME"} to the same effect.
*
* The format of the property string is a comma-separated list of names from the {@link DefaultStringLookup} enum.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code } to {@code "SGVsbG9Xb3JsZCE="}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "SGVsbG9Xb3JsZCE="} to {@code "HelloWorld!"}.
*
* 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. static final) member field. Then the class is loaded and the field's
* value is obtained using reflection.
*
* 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.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code java.awt.event.KeyEvent.VK_ESCAPE} to {@code "27"}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "yyyy-MM-dd"} to todays's date, for example, {@code "2019-08-04"}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* When used through a {@link StringSubstitutor}, this lookup must either be added programmatically (as below) or enabled as a default lookup using the
* {@value #DEFAULT_STRING_LOOKUPS_PROPERTY} system property (see class documentation).
*
* The examples above convert {@code "address|apache.org"} to the IP address of {@code apache.org}.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert (on Linux) {@code "USER"} to the current user name. On Windows 10, you would use {@code "USERNAME"} to the same effect.
*
* If this factory was built using {@link Builder#setFences(Path...)}, then the string lookup is fenced and will throw an {@link IllegalArgumentException}
* if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.
*
* To use a fenced {@link StringLookup}, use {@link StringLookupFactory#builder()}:
*
* To use an unfenced {@link StringLookup}, use {@link StringLookupFactory#INSTANCE}:
*
* To build a fenced StringSubstitutor, use:
*
* Using an unfenced {@link StringSubstitutor}:
*
* The examples above convert {@code "UTF-8:com/domain/document.txt"} to the contents of the file.
*
* To use a {@link StringLookup} fenced by the current directory, use:
*
* The above example converts {@code "UTF-8:com/domain/document.txt"} to the contents of the file.
*
* {@link StringSubstitutor} methods like {@link StringSubstitutor#replace(String)} will throw a {@link IllegalArgumentException} when a file doesn't
* resolves in a fence.
*
* Using a {@link StringLookup} from the {@link StringLookupFactory}:
*
* Using a {@link StringSubstitutor}:
*
* The examples above convert {@code "${sys:os.name}, ${env:USER}"} to the OS name and Linux user name.
*
* Map<String, Object> map = new HashMap<String, Object>();
* map.put("number", Integer.valueOf(2));
* assertEquals("2", StringLookupFactory.biFunctionStringLookup(map).lookup("number", "A context object"));
*
*
* @param key the key to look up, may be null.
* @param object ignored by default.
* @return The matching value, null if no match.
*/
default String lookup(final String key, final U object) {
return apply(key);
}
}
ConstantStringLookup.java 0000664 0000000 0000000 00000013706 15114327406 0035032 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache license, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the license for the specific language governing permissions and
* limitations under the license.
*/
package org.apache.commons.text.lookup;
import java.util.Objects;
import java.util.concurrent.ConcurrentHashMap;
import org.apache.commons.lang3.ClassUtils;
import org.apache.commons.text.StringSubstitutor;
/**
*
* StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");
*
*
* StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));
*
*
* ClassUtils.
*
* @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);
}
/**
* Tries to resolve the specified variable. The passed in variable name is interpreted as the name of a static
* final member field of a class. If the value has already been obtained, it can be retrieved from an internal
* 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 null if it cannot be resolved.
*/
@Override
public synchronized String lookup(final String key) {
if (key == null) {
return null;
}
String result;
result = CONSTANT_CACHE.get(key);
if (result != null) {
return result;
}
final int fieldPos = key.lastIndexOf(FIELD_SEPARATOR);
if (fieldPos < 0) {
return null;
}
try {
final Object value = resolveField(key.substring(0, fieldPos), key.substring(fieldPos + 1));
if (value != null) {
final String string = Objects.toString(value, null);
CONSTANT_CACHE.put(key, string);
result = string;
}
} catch (final Exception ex) {
// TODO it would be nice to log
return null;
}
return result;
}
/**
* Determines the value of the specified constant member field of a class. This implementation will call
* {@code fetchClass()} to obtain the {@link 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 accessible.
*
* @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 ReflectiveOperationException if an error occurs.
*/
protected Object resolveField(final String className, final String fieldName) throws ReflectiveOperationException {
final Class clazz = fetchClass(className);
if (clazz == null) {
return null;
}
return clazz.getField(fieldName).get(null);
}
}
DateStringLookup.java 0000664 0000000 0000000 00000006307 15114327406 0034115 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache license, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the license for the specific language governing permissions and
* limitations under the license.
*/
package org.apache.commons.text.lookup;
import java.text.DateFormat;
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}.
*
* StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");
*
*
* StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));
*
*
*
*
*
* StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org");
*
*
* StringSubstitutor.createInterpolator().replace("... ${dns:address|apache.org} ..."));
*
*
* StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");
*
*
* StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.properties} ..."));
*
*
*
*
*
*
*
*
*
* StringLookupFactory.INSTANCE.javaPlatformStringLookup().lookup("version");
*
*
* StringSubstitutor.createInterpolator().replace("... ${java:version} ..."));
*
*
*
*
* @param key the key to be looked up, may be null.
* @return The value of the environment variable.
*/
@Override
public String lookup(final String key) {
if (key == null) {
return null;
}
switch (key) {
case KEY_VERSION:
return "Java version " + getSystemProperty("java.version");
case KEY_RUNTIME:
return getRuntime();
case KEY_VM:
return getVirtualMachine();
case KEY_OS:
return getOperatingSystem();
case KEY_HARDWARE:
return getHardware();
case KEY_LOCALE:
return getLocale();
default:
throw new IllegalArgumentException(key);
}
}
}
commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup/PathFence.java 0000664 0000000 0000000 00000006261 15114327406 0032572 0 ustar 00root root 0000000 0000000 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache license, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the license for the specific language governing permissions and
* limitations under the license.
*/
package org.apache.commons.text.lookup;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.List;
import java.util.Optional;
import java.util.function.Supplier;
import java.util.stream.Collectors;
/**
* A Path fence guards against using paths outside of a "fence" of made of root paths.
*
* Keep package-private.
*/
final class PathFence {
/**
* Builds {@link PathFence} instances.
*/
static final class Builder implements Supplier
* StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}"));
*
*
* Map<String, Object> map = new HashMap<String, Object>();
* map.put("number", Integer.valueOf(2));
* assertEquals("2", StringLookupFactory.mapStringLookup(map).lookup("number"));
*
*
* @param key the key to look up, may be null.
* @return The matching value, null if no match.
* @since 1.14.0
*/
@Override
default String apply(final String key) {
return lookup(key);
}
/**
* Looks up a String key to provide a String value.
*
* Map<String, Object> map = new HashMap<String, Object>();
* map.put("number", Integer.valueOf(2));
* assertEquals("2", StringLookupFactory.mapStringLookup(map).lookup("number"));
*
*
* @param key the key to look up, may be null.
* @return The matching value, null if no match.
* @deprecated Use {@link #apply(String)}.
*/
@Deprecated
String lookup(String key);
}
StringLookupFactory.java 0000664 0000000 0000000 00000173065 15114327406 0034655 0 ustar 00root root 0000000 0000000 commons-text-rel-commons-text-1.15.0/src/main/java/org/apache/commons/text/lookup /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache license, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the license for the specific language governing permissions and
* limitations under the license.
*/
package org.apache.commons.text.lookup;
import java.net.InetAddress;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.Base64;
import java.util.Collections;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import java.util.Properties;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.function.Supplier;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPathFactory;
import org.apache.commons.text.StringSubstitutor;
/**
* Create instances of string lookups or access singleton string lookups implemented in this package.
*
*
*
*
*
*
*
* Key
* Interface
* Factory Method
* Since
*
*
* {@value #KEY_BASE64_DECODER}
* {@link StringLookup}
* {@link #base64DecoderStringLookup()}
* 1.6
*
*
* {@value #KEY_BASE64_ENCODER}
* {@link StringLookup}
* {@link #base64EncoderStringLookup()}
* 1.6
*
*
* {@value #KEY_CONST}
* {@link StringLookup}
* {@link #constantStringLookup()}
* 1.5
*
*
* {@value #KEY_DATE}
* {@link StringLookup}
* {@link #dateStringLookup()}
* 1.5
*
*
* {@value #KEY_ENV}
* {@link StringLookup}
* {@link #environmentVariableStringLookup()}
* 1.3
*
*
* {@value #KEY_FILE}
* {@link StringLookup}
* {@link #fileStringLookup(Path...)}
* 1.5
*
*
* {@value #KEY_JAVA}
* {@link StringLookup}
* {@link #javaPlatformStringLookup()}
* 1.5
*
*
* {@value #KEY_LOCALHOST}
* {@link StringLookup}
* {@link #localHostStringLookup()}
* 1.3
*
*
* {@value #KEY_LOOPBACK_ADDRESS}
* {@link StringLookup}
* {@link #loopbackAddressStringLookup()}
* 1.13.0
*
*
* {@value #KEY_PROPERTIES}
* {@link StringLookup}
* {@link #propertiesStringLookup(Path...)}
* 1.5
*
*
* {@value #KEY_RESOURCE_BUNDLE}
* {@link StringLookup}
* {@link #resourceBundleStringLookup()}
* 1.6
*
*
* {@value #KEY_SYS}
* {@link StringLookup}
* {@link #systemPropertyStringLookup()}
* 1.3
*
*
* {@value #KEY_URL_DECODER}
* {@link StringLookup}
* {@link #urlDecoderStringLookup()}
* 1.5
*
*
* {@value #KEY_URL_ENCODER}
* {@link StringLookup}
* {@link #urlEncoderStringLookup()}
* 1.5
*
*
* {@value #KEY_XML}
* {@link StringLookup}
* {@link #xmlStringLookup(Map, Path...)}
* 1.5
*
*
* {@value #KEY_XML_DECODER}
* {@link StringLookup}
* {@link #xmlDecoderStringLookup()}
* 1.11.0
*
*
* {@value #KEY_XML_ENCODER}
* {@link StringLookup}
* {@link #xmlEncoderStringLookup()}
* 1.11.0
*
*
*
*
*
* Key
* Interface
* Factory Method
* Since
*
*
* {@value #KEY_DNS}
* {@link StringLookup}
* {@link #dnsStringLookup()}
* 1.8
*
*
* {@value #KEY_URL}
* {@link StringLookup}
* {@link #urlStringLookup()}
* 1.5
*
*
* {@value #KEY_SCRIPT}
* {@link StringLookup}
* {@link #scriptStringLookup()}
* 1.5
*
*
*
* @since 1.3
*/
public final class StringLookupFactory {
/**
* Builds instance of {@link StringLookupFactory}.
*
* @since 1.12.0
*/
public static final class Builder implements Supplier
*
* Interface
* Factory Method
* Since
*
*
* {@link BiStringLookup}
* {@link #biFunctionStringLookup(BiFunction)}
* 1.9
*
*
* {@link StringLookup}
* {@link #functionStringLookup(Function)}
* 1.9
*
* StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
*
*
* StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
*
*
* StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");
*
*
* StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));
*
*
* StringLookupFactory.INSTANCE.environmentVariableStringLookup().lookup("USER");
*
*
* StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));
*
*
* StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
*
*
* StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
*
*
* StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");
*
*
* StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));
*
*
* StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
*
*
* StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
*
*
* StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");
*
*
* StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));
*
*
* StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");
*
*
* StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));
*
*
*
*
*
* StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org");
*
*
* Map<String, StringLookup> lookupMap = new HashMap<>();
* lookupMap.put("dns", StringLookupFactory.INSTANCE.dnsStringLookup());
*
* StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false);
*
* new StringSubstitutor(variableResolver).replace("... ${dns:address|apache.org} ...");
*
*
* StringLookupFactory.INSTANCE.environmentVariableStringLookup().lookup("USER");
*
*
* StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));
*
*
* // Make the fence the current directory
* StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
* factory.fileStringLookup().lookup("UTF-8:com/domain/document.txt");
*
* // throws IllegalArgumentException
* factory.fileStringLookup().lookup("UTF-8:/rootdir/foo/document.txt");
*
* // throws IllegalArgumentException
* factory.fileStringLookup().lookup("UTF-8:../document.txt");
*
*
* Using an unfenced StringLookup
*
* StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");
*
*
* Using a StringLookup with StringSubstitutor
*
* // Make the fence the current directory
* final StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
* final StringSubstitutor stringSubstitutor = new StringSubstitutor(factory.interpolatorStringLookup());
* stringSubstitutor.replace("... ${file:UTF-8:com/domain/document.txt} ..."));
*
* // throws IllegalArgumentException
* stringSubstitutor.replace("... ${file:UTF-8:/rootdir/foo/document.txt} ..."));
*
*
* StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.txt} ..."));
*
*
* StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:com/domain/document.txt");
*
* // throws IllegalArgumentException
* StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:/rootdir/foo/document.txt");
*
* // throws IllegalArgumentException
* StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:../com/domain/document.txt");
*
*
* StringLookupFactory.INSTANCE.interpolatorStringLookup().lookup("${sys:os.name}, ${env:USER}");
*
*
* StringSubstitutor.createInterpolator().replace("... ${sys:os.name}, ${env:USER} ..."));
*
*