/*
 * 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 com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.VisibleForTesting;
import org.checkerframework.checker.nullness.qual.Nullable;

Static utility methods pertaining to String or CharSequence instances. 
Author:
Kevin Bourrillion
Since:
3.0/**
 * 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.
Params:
string – the string to test and possibly return
Returns:
string itself if it is non-null; "" if it is null/**
   * 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; null otherwise. 
Params:
string – the string to test and possibly return
Returns:
string itself if it is nonempty; null if it is empty or null/**
   * 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 true if the given string is null or is the empty string. 
Consider normalizing your string references with nullToEmpty. If you do, you can use String.isEmpty() instead of this method, and you won't need special null-safe forms of methods like String.toUpperCase either. Or, if you'd like to normalize "in the other direction," converting empty strings to null, you can use emptyToNull. 
Params:
string – a string reference to check
Returns:
true if the string is null or is the empty 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 minLength, consisting of string prepended with as many copies of padChar as are necessary to reach that length. For example, 

  
padStart("7", 3, '0') returns "007" 
padStart("2010", 3, '0') returns "2010" 
See Formatter for a richer set of formatting capabilities. 
Params:
string – the string which should appear at the end of the result
minLength – the minimum length the resulting string must have. Can be zero or negative, in
    which case the input string is always returned.
padChar – the character to insert at the beginning of the result until the minimum length
    is reached
Returns:
the padded 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 minLength, consisting of string appended with as many copies of padChar as are necessary to reach that length. For example, 

  
padEnd("4.", 5, '0') returns "4.000" 
padEnd("2010", 3, '!') returns "2010" 
See Formatter for a richer set of formatting capabilities. 
Params:
string – the string which should appear at the beginning of the result
minLength – the minimum length the resulting string must have. Can be zero or negative, in
    which case the input string is always returned.
padChar – the character to append to the end of the result until the minimum length is
    reached
Returns:
the padded string/**
   * 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, repeat("hey", 3) returns the string "heyheyhey". 
Params:
string – any non-null string
count – the number of times to repeat it; a nonnegative integer
Throws:
IllegalArgumentException – if count is negative
Returns:
a string containing string repeated count times (the empty string if count is zero)/**
   * 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 prefix such that a.toString().startsWith(prefix) &&
b.toString().startsWith(prefix), taking care not to split surrogate pairs. If a and b have no common prefix, returns the empty string. 
Since:
11.0/**
   * 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 suffix such that a.toString().endsWith(suffix) &&
b.toString().endsWith(suffix), taking care not to split surrogate pairs. If a and b have no common suffix, returns the empty string. 
Since:
11.0/**
   * 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();
  }

  
Returns the given template string with each occurrence of "%s" replaced with the corresponding argument value from 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 any circumstances (as long as all arguments' toString methods successfully return). 
Note: For most string-formatting needs, use String.format, format.format, and related methods. These support the full range of format specifiers, and alert you to usage errors by throwing InvalidFormatException. 
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 
String.format is not available. As an example, method implementations of the Preconditions class use this formatter, for both of the reasons just discussed. 
Warning: Only the exact two-character placeholder sequence "%s" is recognized. 
Params:
template – a string containing zero or more "%s" placeholder sequences. 
    null is treated as the four-character string "null".
args – the arguments to be substituted into the message template. The first argument specified is substituted for the first occurrence of "%s" in the template, and so forth. A null argument is converted to the four-character string "null"; non-null values are converted to strings using Object.toString().
Since:
25.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 any
   * circumstances (as long as all arguments' {@code toString} methods successfully return).
   *
   * <p><b>Note:</b> For most string-formatting needs, use {@link String#format}, {@link
   * PrintWriter#format}, and related methods. These support the full range of {@linkplain
   * Formatter#syntax format specifiers}, and alert you to usage errors by throwing {@link
   * InvalidFormatException}.
   *
   * <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
  // TODO(diamondm) capture exceptions thrown from arguments' toString methods
  public static String lenientFormat(
      @Nullable String template, @Nullable Object @Nullable... args) {
    template = String.valueOf(template); // null -> "null"

    args = args == null ? new Object[] {"(Object[])null"} : args;

    // 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();
  }

  
True when a valid surrogate pair starts at the given index in the given string. Out-of-range indexes return false. /**
   * 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));
  }
}