| /* |
| * Copyright (C) 2010 The Guava Authors |
| * |
| * Licensed 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 |
| * |
| * http://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 com.google.common.base; |
| |
| import static com.google.common.base.Preconditions.checkArgument; |
| import static com.google.common.base.Preconditions.checkNotNull; |
| import static java.util.logging.Level.WARNING; |
| |
| import com.google.common.annotations.GwtCompatible; |
| import com.google.common.annotations.VisibleForTesting; |
| import java.util.logging.Logger; |
| import org.checkerframework.checker.nullness.qual.Nullable; |
| |
| /** |
| * Static utility methods pertaining to {@code String} or {@code CharSequence} instances. |
| * |
| * @author Kevin Bourrillion |
| * @since 3.0 |
| */ |
| @GwtCompatible |
| public final class Strings { |
| private Strings() {} |
| |
| /** |
| * Returns the given string if it is non-null; the empty string otherwise. |
| * |
| * @param string the string to test and possibly return |
| * @return {@code string} itself if it is non-null; {@code ""} if it is null |
| */ |
| public static String nullToEmpty(@Nullable String string) { |
| return Platform.nullToEmpty(string); |
| } |
| |
| /** |
| * Returns the given string if it is nonempty; {@code null} otherwise. |
| * |
| * @param string the string to test and possibly return |
| * @return {@code string} itself if it is nonempty; {@code null} if it is empty or null |
| */ |
| public static @Nullable String emptyToNull(@Nullable String string) { |
| return Platform.emptyToNull(string); |
| } |
| |
| /** |
| * Returns {@code true} if the given string is null or is the empty string. |
| * |
| * <p>Consider normalizing your string references with {@link #nullToEmpty}. If you do, you can |
| * use {@link String#isEmpty()} instead of this method, and you won't need special null-safe forms |
| * of methods like {@link String#toUpperCase} either. Or, if you'd like to normalize "in the other |
| * direction," converting empty strings to {@code null}, you can use {@link #emptyToNull}. |
| * |
| * @param string a string reference to check |
| * @return {@code true} if the string is null or is the empty string |
| */ |
| public static boolean isNullOrEmpty(@Nullable String string) { |
| return Platform.stringIsNullOrEmpty(string); |
| } |
| |
| /** |
| * Returns a string, of length at least {@code minLength}, consisting of {@code string} prepended |
| * with as many copies of {@code padChar} as are necessary to reach that length. For example, |
| * |
| * <ul> |
| * <li>{@code padStart("7", 3, '0')} returns {@code "007"} |
| * <li>{@code padStart("2010", 3, '0')} returns {@code "2010"} |
| * </ul> |
| * |
| * <p>See {@link java.util.Formatter} for a richer set of formatting capabilities. |
| * |
| * @param string the string which should appear at the end of the result |
| * @param minLength the minimum length the resulting string must have. Can be zero or negative, in |
| * which case the input string is always returned. |
| * @param padChar the character to insert at the beginning of the result until the minimum length |
| * is reached |
| * @return the padded string |
| */ |
| public static String padStart(String string, int minLength, char padChar) { |
| checkNotNull(string); // eager for GWT. |
| if (string.length() >= minLength) { |
| return string; |
| } |
| StringBuilder sb = new StringBuilder(minLength); |
| for (int i = string.length(); i < minLength; i++) { |
| sb.append(padChar); |
| } |
| sb.append(string); |
| return sb.toString(); |
| } |
| |
| /** |
| * Returns a string, of length at least {@code minLength}, consisting of {@code string} appended |
| * with as many copies of {@code padChar} as are necessary to reach that length. For example, |
| * |
| * <ul> |
| * <li>{@code padEnd("4.", 5, '0')} returns {@code "4.000"} |
| * <li>{@code padEnd("2010", 3, '!')} returns {@code "2010"} |
| * </ul> |
| * |
| * <p>See {@link java.util.Formatter} for a richer set of formatting capabilities. |
| * |
| * @param string the string which should appear at the beginning of the result |
| * @param minLength the minimum length the resulting string must have. Can be zero or negative, in |
| * which case the input string is always returned. |
| * @param padChar the character to append to the end of the result until the minimum length is |
| * reached |
| * @return the padded string |
| */ |
| public static String padEnd(String string, int minLength, char padChar) { |
| checkNotNull(string); // eager for GWT. |
| if (string.length() >= minLength) { |
| return string; |
| } |
| StringBuilder sb = new StringBuilder(minLength); |
| sb.append(string); |
| for (int i = string.length(); i < minLength; i++) { |
| sb.append(padChar); |
| } |
| return sb.toString(); |
| } |
| |
| /** |
| * Returns a string consisting of a specific number of concatenated copies of an input string. For |
| * example, {@code repeat("hey", 3)} returns the string {@code "heyheyhey"}. |
| * |
| * @param string any non-null string |
| * @param count the number of times to repeat it; a nonnegative integer |
| * @return a string containing {@code string} repeated {@code count} times (the empty string if |
| * {@code count} is zero) |
| * @throws IllegalArgumentException if {@code count} is negative |
| */ |
| public static String repeat(String string, int count) { |
| checkNotNull(string); // eager for GWT. |
| |
| if (count <= 1) { |
| checkArgument(count >= 0, "invalid count: %s", count); |
| return (count == 0) ? "" : string; |
| } |
| |
| // IF YOU MODIFY THE CODE HERE, you must update StringsRepeatBenchmark |
| final int len = string.length(); |
| final long longSize = (long) len * (long) count; |
| final int size = (int) longSize; |
| if (size != longSize) { |
| throw new ArrayIndexOutOfBoundsException("Required array size too large: " + longSize); |
| } |
| |
| final char[] array = new char[size]; |
| string.getChars(0, len, array, 0); |
| int n; |
| for (n = len; n < size - n; n <<= 1) { |
| System.arraycopy(array, 0, array, n, n); |
| } |
| System.arraycopy(array, 0, array, n, size - n); |
| return new String(array); |
| } |
| |
| /** |
| * Returns the longest string {@code prefix} such that {@code a.toString().startsWith(prefix) && |
| * b.toString().startsWith(prefix)}, taking care not to split surrogate pairs. If {@code a} and |
| * {@code b} have no common prefix, returns the empty string. |
| * |
| * @since 11.0 |
| */ |
| public static String commonPrefix(CharSequence a, CharSequence b) { |
| checkNotNull(a); |
| checkNotNull(b); |
| |
| int maxPrefixLength = Math.min(a.length(), b.length()); |
| int p = 0; |
| while (p < maxPrefixLength && a.charAt(p) == b.charAt(p)) { |
| p++; |
| } |
| if (validSurrogatePairAt(a, p - 1) || validSurrogatePairAt(b, p - 1)) { |
| p--; |
| } |
| return a.subSequence(0, p).toString(); |
| } |
| |
| /** |
| * Returns the longest string {@code suffix} such that {@code a.toString().endsWith(suffix) && |
| * b.toString().endsWith(suffix)}, taking care not to split surrogate pairs. If {@code a} and |
| * {@code b} have no common suffix, returns the empty string. |
| * |
| * @since 11.0 |
| */ |
| public static String commonSuffix(CharSequence a, CharSequence b) { |
| checkNotNull(a); |
| checkNotNull(b); |
| |
| int maxSuffixLength = Math.min(a.length(), b.length()); |
| int s = 0; |
| while (s < maxSuffixLength && a.charAt(a.length() - s - 1) == b.charAt(b.length() - s - 1)) { |
| s++; |
| } |
| if (validSurrogatePairAt(a, a.length() - s - 1) |
| || validSurrogatePairAt(b, b.length() - s - 1)) { |
| s--; |
| } |
| return a.subSequence(a.length() - s, a.length()).toString(); |
| } |
| |
| /** |
| * True when a valid surrogate pair starts at the given {@code index} in the given {@code string}. |
| * Out-of-range indexes return false. |
| */ |
| @VisibleForTesting |
| static boolean validSurrogatePairAt(CharSequence string, int index) { |
| return index >= 0 |
| && index <= (string.length() - 2) |
| && Character.isHighSurrogate(string.charAt(index)) |
| && Character.isLowSurrogate(string.charAt(index + 1)); |
| } |
| |
| /** |
| * Returns the given {@code template} string with each occurrence of {@code "%s"} replaced with |
| * the corresponding argument value from {@code args}; or, if the placeholder and argument counts |
| * do not match, returns a best-effort form of that string. Will not throw an exception under |
| * normal conditions. |
| * |
| * <p><b>Note:</b> For most string-formatting needs, use {@link String#format String.format}, |
| * {@link java.io.PrintWriter#format PrintWriter.format}, and related methods. These support the |
| * full range of <a |
| * href="https://docs.oracle.com/javase/9/docs/api/java/util/Formatter.html#syntax">format |
| * specifiers</a>, and alert you to usage errors by throwing {@link |
| * java.util.IllegalFormatException}. |
| * |
| * <p>In certain cases, such as outputting debugging information or constructing a message to be |
| * used for another unchecked exception, an exception during string formatting would serve little |
| * purpose except to supplant the real information you were trying to provide. These are the cases |
| * this method is made for; it instead generates a best-effort string with all supplied argument |
| * values present. This method is also useful in environments such as GWT where {@code |
| * String.format} is not available. As an example, method implementations of the {@link |
| * Preconditions} class use this formatter, for both of the reasons just discussed. |
| * |
| * <p><b>Warning:</b> Only the exact two-character placeholder sequence {@code "%s"} is |
| * recognized. |
| * |
| * @param template a string containing zero or more {@code "%s"} placeholder sequences. {@code |
| * null} is treated as the four-character string {@code "null"}. |
| * @param args the arguments to be substituted into the message template. The first argument |
| * specified is substituted for the first occurrence of {@code "%s"} in the template, and so |
| * forth. A {@code null} argument is converted to the four-character string {@code "null"}; |
| * non-null values are converted to strings using {@link Object#toString()}. |
| * @since 25.1 |
| */ |
| // TODO(diamondm) consider using Arrays.toString() for array parameters |
| public static String lenientFormat( |
| @Nullable String template, @Nullable Object @Nullable ... args) { |
| template = String.valueOf(template); // null -> "null" |
| |
| if (args == null) { |
| args = new Object[] {"(Object[])null"}; |
| } else { |
| for (int i = 0; i < args.length; i++) { |
| args[i] = lenientToString(args[i]); |
| } |
| } |
| |
| // start substituting the arguments into the '%s' placeholders |
| StringBuilder builder = new StringBuilder(template.length() + 16 * args.length); |
| int templateStart = 0; |
| int i = 0; |
| while (i < args.length) { |
| int placeholderStart = template.indexOf("%s", templateStart); |
| if (placeholderStart == -1) { |
| break; |
| } |
| builder.append(template, templateStart, placeholderStart); |
| builder.append(args[i++]); |
| templateStart = placeholderStart + 2; |
| } |
| builder.append(template, templateStart, template.length()); |
| |
| // if we run out of placeholders, append the extra args in square braces |
| if (i < args.length) { |
| builder.append(" ["); |
| builder.append(args[i++]); |
| while (i < args.length) { |
| builder.append(", "); |
| builder.append(args[i++]); |
| } |
| builder.append(']'); |
| } |
| |
| return builder.toString(); |
| } |
| |
| private static String lenientToString(@Nullable Object o) { |
| if (o == null) { |
| return "null"; |
| } |
| try { |
| return o.toString(); |
| } catch (Exception e) { |
| // Default toString() behavior - see Object.toString() |
| String objectToString = |
| o.getClass().getName() + '@' + Integer.toHexString(System.identityHashCode(o)); |
| // Logger is created inline with fixed name to avoid forcing Proguard to create another class. |
| Logger.getLogger("com.google.common.base.Strings") |
| .log(WARNING, "Exception during lenientFormat for " + objectToString, e); |
| return "<" + objectToString + " threw " + e.getClass().getName() + ">"; |
| } |
| } |
| } |