1 /* 2 * Copyright (C) 2010 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.base; 18 19 import static com.google.common.base.Preconditions.checkArgument; 20 import static com.google.common.base.Preconditions.checkNotNull; 21 22 import com.google.common.annotations.GwtCompatible; 23 import com.google.common.annotations.VisibleForTesting; 24 25 import java.util.Formatter; 26 27 import javax.annotation.Nullable; 28 29 /** 30 * Static utility methods pertaining to {@code String} or {@code CharSequence} 31 * instances. 32 * 33 * @author Kevin Bourrillion 34 * @since 3.0 35 */ 36 @GwtCompatible 37 public final class Strings { Strings()38 private Strings() {} 39 40 /** 41 * Returns the given string if it is non-null; the empty string otherwise. 42 * 43 * @param string the string to test and possibly return 44 * @return {@code string} itself if it is non-null; {@code ""} if it is null 45 */ nullToEmpty(@ullable String string)46 public static String nullToEmpty(@Nullable String string) { 47 return (string == null) ? "" : string; 48 } 49 50 /** 51 * Returns the given string if it is nonempty; {@code null} otherwise. 52 * 53 * @param string the string to test and possibly return 54 * @return {@code string} itself if it is nonempty; {@code null} if it is 55 * empty or null 56 */ 57 @Nullable emptyToNull(@ullable String string)58 public static String emptyToNull(@Nullable String string) { 59 return isNullOrEmpty(string) ? null : string; 60 } 61 62 /** 63 * Returns {@code true} if the given string is null or is the empty string. 64 * 65 * <p>Consider normalizing your string references with {@link #nullToEmpty}. 66 * If you do, you can use {@link String#isEmpty()} instead of this 67 * method, and you won't need special null-safe forms of methods like {@link 68 * String#toUpperCase} either. Or, if you'd like to normalize "in the other 69 * direction," converting empty strings to {@code null}, you can use {@link 70 * #emptyToNull}. 71 * 72 * @param string a string reference to check 73 * @return {@code true} if the string is null or is the empty string 74 */ isNullOrEmpty(@ullable String string)75 public static boolean isNullOrEmpty(@Nullable String string) { 76 return string == null || string.length() == 0; // string.isEmpty() in Java 6 77 } 78 79 /** 80 * Returns a string, of length at least {@code minLength}, consisting of 81 * {@code string} prepended with as many copies of {@code padChar} as are 82 * necessary to reach that length. For example, 83 * 84 * <ul> 85 * <li>{@code padStart("7", 3, '0')} returns {@code "007"} 86 * <li>{@code padStart("2010", 3, '0')} returns {@code "2010"} 87 * </ul> 88 * 89 * <p>See {@link Formatter} for a richer set of formatting capabilities. 90 * 91 * @param string the string which should appear at the end of the result 92 * @param minLength the minimum length the resulting string must have. Can be 93 * zero or negative, in which case the input string is always returned. 94 * @param padChar the character to insert at the beginning of the result until 95 * the minimum length is reached 96 * @return the padded string 97 */ padStart(String string, int minLength, char padChar)98 public static String padStart(String string, int minLength, char padChar) { 99 checkNotNull(string); // eager for GWT. 100 if (string.length() >= minLength) { 101 return string; 102 } 103 StringBuilder sb = new StringBuilder(minLength); 104 for (int i = string.length(); i < minLength; i++) { 105 sb.append(padChar); 106 } 107 sb.append(string); 108 return sb.toString(); 109 } 110 111 /** 112 * Returns a string, of length at least {@code minLength}, consisting of 113 * {@code string} appended with as many copies of {@code padChar} as are 114 * necessary to reach that length. For example, 115 * 116 * <ul> 117 * <li>{@code padEnd("4.", 5, '0')} returns {@code "4.000"} 118 * <li>{@code padEnd("2010", 3, '!')} returns {@code "2010"} 119 * </ul> 120 * 121 * <p>See {@link Formatter} for a richer set of formatting capabilities. 122 * 123 * @param string the string which should appear at the beginning of the result 124 * @param minLength the minimum length the resulting string must have. Can be 125 * zero or negative, in which case the input string is always returned. 126 * @param padChar the character to append to the end of the result until the 127 * minimum length is reached 128 * @return the padded string 129 */ padEnd(String string, int minLength, char padChar)130 public static String padEnd(String string, int minLength, char padChar) { 131 checkNotNull(string); // eager for GWT. 132 if (string.length() >= minLength) { 133 return string; 134 } 135 StringBuilder sb = new StringBuilder(minLength); 136 sb.append(string); 137 for (int i = string.length(); i < minLength; i++) { 138 sb.append(padChar); 139 } 140 return sb.toString(); 141 } 142 143 /** 144 * Returns a string consisting of a specific number of concatenated copies of 145 * an input string. For example, {@code repeat("hey", 3)} returns the string 146 * {@code "heyheyhey"}. 147 * 148 * @param string any non-null string 149 * @param count the number of times to repeat it; a nonnegative integer 150 * @return a string containing {@code string} repeated {@code count} times 151 * (the empty string if {@code count} is zero) 152 * @throws IllegalArgumentException if {@code count} is negative 153 */ repeat(String string, int count)154 public static String repeat(String string, int count) { 155 checkNotNull(string); // eager for GWT. 156 157 if (count <= 1) { 158 checkArgument(count >= 0, "invalid count: %s", count); 159 return (count == 0) ? "" : string; 160 } 161 162 // IF YOU MODIFY THE CODE HERE, you must update StringsRepeatBenchmark 163 final int len = string.length(); 164 final long longSize = (long) len * (long) count; 165 final int size = (int) longSize; 166 if (size != longSize) { 167 throw new ArrayIndexOutOfBoundsException( 168 "Required array size too large: " + longSize); 169 } 170 171 final char[] array = new char[size]; 172 string.getChars(0, len, array, 0); 173 int n; 174 for (n = len; n < size - n; n <<= 1) { 175 System.arraycopy(array, 0, array, n, n); 176 } 177 System.arraycopy(array, 0, array, n, size - n); 178 return new String(array); 179 } 180 181 /** 182 * Returns the longest string {@code prefix} such that 183 * {@code a.toString().startsWith(prefix) && b.toString().startsWith(prefix)}, 184 * taking care not to split surrogate pairs. If {@code a} and {@code b} have 185 * no common prefix, returns the empty string. 186 * 187 * @since 11.0 188 */ commonPrefix(CharSequence a, CharSequence b)189 public static String commonPrefix(CharSequence a, CharSequence b) { 190 checkNotNull(a); 191 checkNotNull(b); 192 193 int maxPrefixLength = Math.min(a.length(), b.length()); 194 int p = 0; 195 while (p < maxPrefixLength && a.charAt(p) == b.charAt(p)) { 196 p++; 197 } 198 if (validSurrogatePairAt(a, p - 1) || validSurrogatePairAt(b, p - 1)) { 199 p--; 200 } 201 return a.subSequence(0, p).toString(); 202 } 203 204 /** 205 * Returns the longest string {@code suffix} such that 206 * {@code a.toString().endsWith(suffix) && b.toString().endsWith(suffix)}, 207 * taking care not to split surrogate pairs. If {@code a} and {@code b} have 208 * no common suffix, returns the empty string. 209 * 210 * @since 11.0 211 */ commonSuffix(CharSequence a, CharSequence b)212 public static String commonSuffix(CharSequence a, CharSequence b) { 213 checkNotNull(a); 214 checkNotNull(b); 215 216 int maxSuffixLength = Math.min(a.length(), b.length()); 217 int s = 0; 218 while (s < maxSuffixLength 219 && a.charAt(a.length() - s - 1) == b.charAt(b.length() - s - 1)) { 220 s++; 221 } 222 if (validSurrogatePairAt(a, a.length() - s - 1) 223 || validSurrogatePairAt(b, b.length() - s - 1)) { 224 s--; 225 } 226 return a.subSequence(a.length() - s, a.length()).toString(); 227 } 228 229 /** 230 * True when a valid surrogate pair starts at the given {@code index} in the 231 * given {@code string}. Out-of-range indexes return false. 232 */ 233 @VisibleForTesting validSurrogatePairAt(CharSequence string, int index)234 static boolean validSurrogatePairAt(CharSequence string, int index) { 235 return index >= 0 && index <= (string.length() - 2) 236 && Character.isHighSurrogate(string.charAt(index)) 237 && Character.isLowSurrogate(string.charAt(index + 1)); 238 } 239 } 240