001/*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static java.util.logging.Level.WARNING;
020
021import com.google.common.annotations.GwtCompatible;
022import com.google.common.annotations.VisibleForTesting;
023import java.util.logging.Logger;
024import org.checkerframework.checker.nullness.qual.Nullable;
025
026/**
027 * Static utility methods pertaining to {@code String} or {@code CharSequence} instances.
028 *
029 * @author Kevin Bourrillion
030 * @since 3.0
031 */
032@GwtCompatible
033public final class Strings {
034  private Strings() {}
035
036  /**
037   * Returns the given string if it is non-null; the empty string otherwise.
038   *
039   * @param string the string to test and possibly return
040   * @return {@code string} itself if it is non-null; {@code ""} if it is null
041   */
042  public static String nullToEmpty(@Nullable String string) {
043    return Platform.nullToEmpty(string);
044  }
045
046  /**
047   * Returns the given string if it is nonempty; {@code null} otherwise.
048   *
049   * @param string the string to test and possibly return
050   * @return {@code string} itself if it is nonempty; {@code null} if it is empty or null
051   */
052  public static @Nullable String emptyToNull(@Nullable String string) {
053    return Platform.emptyToNull(string);
054  }
055
056  /**
057   * Returns {@code true} if the given string is null or is the empty string.
058   *
059   * <p>Consider normalizing your string references with {@link #nullToEmpty}. If you do, you can
060   * use {@link String#isEmpty()} instead of this method, and you won't need special null-safe forms
061   * of methods like {@link String#toUpperCase} either. Or, if you'd like to normalize "in the other
062   * direction," converting empty strings to {@code null}, you can use {@link #emptyToNull}.
063   *
064   * @param string a string reference to check
065   * @return {@code true} if the string is null or is the empty string
066   */
067  public static boolean isNullOrEmpty(@Nullable String string) {
068    return Platform.stringIsNullOrEmpty(string);
069  }
070
071  /**
072   * Returns a string, of length at least {@code minLength}, consisting of {@code string} prepended
073   * with as many copies of {@code padChar} as are necessary to reach that length. For example,
074   *
075   * <ul>
076   *   <li>{@code padStart("7", 3, '0')} returns {@code "007"}
077   *   <li>{@code padStart("2010", 3, '0')} returns {@code "2010"}
078   * </ul>
079   *
080   * <p>See {@link java.util.Formatter} for a richer set of formatting capabilities.
081   *
082   * @param string the string which should appear at the end of the result
083   * @param minLength the minimum length the resulting string must have. Can be zero or negative, in
084   *     which case the input string is always returned.
085   * @param padChar the character to insert at the beginning of the result until the minimum length
086   *     is reached
087   * @return the padded string
088   */
089  public static String padStart(String string, int minLength, char padChar) {
090    checkNotNull(string); // eager for GWT.
091    if (string.length() >= minLength) {
092      return string;
093    }
094    StringBuilder sb = new StringBuilder(minLength);
095    for (int i = string.length(); i < minLength; i++) {
096      sb.append(padChar);
097    }
098    sb.append(string);
099    return sb.toString();
100  }
101
102  /**
103   * Returns a string, of length at least {@code minLength}, consisting of {@code string} appended
104   * with as many copies of {@code padChar} as are necessary to reach that length. For example,
105   *
106   * <ul>
107   *   <li>{@code padEnd("4.", 5, '0')} returns {@code "4.000"}
108   *   <li>{@code padEnd("2010", 3, '!')} returns {@code "2010"}
109   * </ul>
110   *
111   * <p>See {@link java.util.Formatter} for a richer set of formatting capabilities.
112   *
113   * @param string the string which should appear at the beginning of the result
114   * @param minLength the minimum length the resulting string must have. Can be zero or negative, in
115   *     which case the input string is always returned.
116   * @param padChar the character to append to the end of the result until the minimum length is
117   *     reached
118   * @return the padded string
119   */
120  public static String padEnd(String string, int minLength, char padChar) {
121    checkNotNull(string); // eager for GWT.
122    if (string.length() >= minLength) {
123      return string;
124    }
125    StringBuilder sb = new StringBuilder(minLength);
126    sb.append(string);
127    for (int i = string.length(); i < minLength; i++) {
128      sb.append(padChar);
129    }
130    return sb.toString();
131  }
132
133  /**
134   * Returns a string consisting of a specific number of concatenated copies of an input string. For
135   * example, {@code repeat("hey", 3)} returns the string {@code "heyheyhey"}.
136   *
137   * @param string any non-null string
138   * @param count the number of times to repeat it; a nonnegative integer
139   * @return a string containing {@code string} repeated {@code count} times (the empty string if
140   *     {@code count} is zero)
141   * @throws IllegalArgumentException if {@code count} is negative
142   */
143  public static String repeat(String string, int count) {
144    checkNotNull(string); // eager for GWT.
145
146    if (count <= 1) {
147      checkArgument(count >= 0, "invalid count: %s", count);
148      return (count == 0) ? "" : string;
149    }
150
151    // IF YOU MODIFY THE CODE HERE, you must update StringsRepeatBenchmark
152    final int len = string.length();
153    final long longSize = (long) len * (long) count;
154    final int size = (int) longSize;
155    if (size != longSize) {
156      throw new ArrayIndexOutOfBoundsException("Required array size too large: " + longSize);
157    }
158
159    final char[] array = new char[size];
160    string.getChars(0, len, array, 0);
161    int n;
162    for (n = len; n < size - n; n <<= 1) {
163      System.arraycopy(array, 0, array, n, n);
164    }
165    System.arraycopy(array, 0, array, n, size - n);
166    return new String(array);
167  }
168
169  /**
170   * Returns the longest string {@code prefix} such that {@code a.toString().startsWith(prefix) &&
171   * b.toString().startsWith(prefix)}, taking care not to split surrogate pairs. If {@code a} and
172   * {@code b} have no common prefix, returns the empty string.
173   *
174   * @since 11.0
175   */
176  public static String commonPrefix(CharSequence a, CharSequence b) {
177    checkNotNull(a);
178    checkNotNull(b);
179
180    int maxPrefixLength = Math.min(a.length(), b.length());
181    int p = 0;
182    while (p < maxPrefixLength && a.charAt(p) == b.charAt(p)) {
183      p++;
184    }
185    if (validSurrogatePairAt(a, p - 1) || validSurrogatePairAt(b, p - 1)) {
186      p--;
187    }
188    return a.subSequence(0, p).toString();
189  }
190
191  /**
192   * Returns the longest string {@code suffix} such that {@code a.toString().endsWith(suffix) &&
193   * b.toString().endsWith(suffix)}, taking care not to split surrogate pairs. If {@code a} and
194   * {@code b} have no common suffix, returns the empty string.
195   *
196   * @since 11.0
197   */
198  public static String commonSuffix(CharSequence a, CharSequence b) {
199    checkNotNull(a);
200    checkNotNull(b);
201
202    int maxSuffixLength = Math.min(a.length(), b.length());
203    int s = 0;
204    while (s < maxSuffixLength && a.charAt(a.length() - s - 1) == b.charAt(b.length() - s - 1)) {
205      s++;
206    }
207    if (validSurrogatePairAt(a, a.length() - s - 1)
208        || validSurrogatePairAt(b, b.length() - s - 1)) {
209      s--;
210    }
211    return a.subSequence(a.length() - s, a.length()).toString();
212  }
213
214  /**
215   * True when a valid surrogate pair starts at the given {@code index} in the given {@code string}.
216   * Out-of-range indexes return false.
217   */
218  @VisibleForTesting
219  static boolean validSurrogatePairAt(CharSequence string, int index) {
220    return index >= 0
221        && index <= (string.length() - 2)
222        && Character.isHighSurrogate(string.charAt(index))
223        && Character.isLowSurrogate(string.charAt(index + 1));
224  }
225
226  /**
227   * Returns the given {@code template} string with each occurrence of {@code "%s"} replaced with
228   * the corresponding argument value from {@code args}; or, if the placeholder and argument counts
229   * do not match, returns a best-effort form of that string. Will not throw an exception under
230   * normal conditions.
231   *
232   * <p><b>Note:</b> For most string-formatting needs, use {@link String#format String.format},
233   * {@link java.io.PrintWriter#format PrintWriter.format}, and related methods. These support the
234   * full range of <a
235   * href="https://docs.oracle.com/javase/9/docs/api/java/util/Formatter.html#syntax">format
236   * specifiers</a>, and alert you to usage errors by throwing {@link
237   * java.util.IllegalFormatException}.
238   *
239   * <p>In certain cases, such as outputting debugging information or constructing a message to be
240   * used for another unchecked exception, an exception during string formatting would serve little
241   * purpose except to supplant the real information you were trying to provide. These are the cases
242   * this method is made for; it instead generates a best-effort string with all supplied argument
243   * values present. This method is also useful in environments such as GWT where {@code
244   * String.format} is not available. As an example, method implementations of the {@link
245   * Preconditions} class use this formatter, for both of the reasons just discussed.
246   *
247   * <p><b>Warning:</b> Only the exact two-character placeholder sequence {@code "%s"} is
248   * recognized.
249   *
250   * @param template a string containing zero or more {@code "%s"} placeholder sequences. {@code
251   *     null} is treated as the four-character string {@code "null"}.
252   * @param args the arguments to be substituted into the message template. The first argument
253   *     specified is substituted for the first occurrence of {@code "%s"} in the template, and so
254   *     forth. A {@code null} argument is converted to the four-character string {@code "null"};
255   *     non-null values are converted to strings using {@link Object#toString()}.
256   * @since 25.1
257   */
258  // TODO(diamondm) consider using Arrays.toString() for array parameters
259  public static String lenientFormat(
260      @Nullable String template, @Nullable Object @Nullable... args) {
261    template = String.valueOf(template); // null -> "null"
262
263    if (args == null) {
264      args = new Object[] {"(Object[])null"};
265    } else {
266      for (int i = 0; i < args.length; i++) {
267        args[i] = lenientToString(args[i]);
268      }
269    }
270
271    // start substituting the arguments into the '%s' placeholders
272    StringBuilder builder = new StringBuilder(template.length() + 16 * args.length);
273    int templateStart = 0;
274    int i = 0;
275    while (i < args.length) {
276      int placeholderStart = template.indexOf("%s", templateStart);
277      if (placeholderStart == -1) {
278        break;
279      }
280      builder.append(template, templateStart, placeholderStart);
281      builder.append(args[i++]);
282      templateStart = placeholderStart + 2;
283    }
284    builder.append(template, templateStart, template.length());
285
286    // if we run out of placeholders, append the extra args in square braces
287    if (i < args.length) {
288      builder.append(" [");
289      builder.append(args[i++]);
290      while (i < args.length) {
291        builder.append(", ");
292        builder.append(args[i++]);
293      }
294      builder.append(']');
295    }
296
297    return builder.toString();
298  }
299
300  private static String lenientToString(@Nullable Object o) {
301    try {
302      return String.valueOf(o);
303    } catch (Exception e) {
304      // Default toString() behavior - see Object.toString()
305      String objectToString =
306          o.getClass().getName() + '@' + Integer.toHexString(System.identityHashCode(o));
307      // Logger is created inline with fixed name to avoid forcing Proguard to create another class.
308      Logger.getLogger("com.google.common.base.Strings")
309          .log(WARNING, "Exception during lenientFormat for " + objectToString, e);
310      return "<" + objectToString + " threw " + e.getClass().getName() + ">";
311    }
312  }
313}