001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.codec.binary; 019 020import java.io.UnsupportedEncodingException; 021import java.nio.ByteBuffer; 022import java.nio.charset.Charset; 023 024import org.apache.commons.codec.CharEncoding; 025import org.apache.commons.codec.Charsets; 026 027/** 028 * Converts String to and from bytes using the encodings required by the Java specification. These encodings are 029 * specified in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html"> 030 * Standard charsets</a>. 031 * 032 * <p>This class is immutable and thread-safe.</p> 033 * 034 * @see CharEncoding 035 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 036 * @version $Id$ 037 * @since 1.4 038 */ 039public class StringUtils { 040 041 /** 042 * <p> 043 * Compares two CharSequences, returning <code>true</code> if they represent equal sequences of characters. 044 * </p> 045 * 046 * <p> 047 * <code>null</code>s are handled without exceptions. Two <code>null</code> references are considered to be equal. 048 * The comparison is case sensitive. 049 * </p> 050 * 051 * <pre> 052 * StringUtils.equals(null, null) = true 053 * StringUtils.equals(null, "abc") = false 054 * StringUtils.equals("abc", null) = false 055 * StringUtils.equals("abc", "abc") = true 056 * StringUtils.equals("abc", "ABC") = false 057 * </pre> 058 * 059 * <p> 060 * Copied from Apache Commons Lang r1583482 on April 10, 2014 (day of 3.3.2 release). 061 * </p> 062 * 063 * @see Object#equals(Object) 064 * @param cs1 065 * the first CharSequence, may be <code>null</code> 066 * @param cs2 067 * the second CharSequence, may be <code>null</code> 068 * @return <code>true</code> if the CharSequences are equal (case-sensitive), or both <code>null</code> 069 * @since 1.10 070 */ 071 public static boolean equals(final CharSequence cs1, final CharSequence cs2) { 072 if (cs1 == cs2) { 073 return true; 074 } 075 if (cs1 == null || cs2 == null) { 076 return false; 077 } 078 if (cs1 instanceof String && cs2 instanceof String) { 079 return cs1.equals(cs2); 080 } 081 return cs1.length() == cs2.length() && CharSequenceUtils.regionMatches(cs1, false, 0, cs2, 0, cs1.length()); 082 } 083 084 /** 085 * Calls {@link String#getBytes(Charset)} 086 * 087 * @param string 088 * The string to encode (if null, return null). 089 * @param charset 090 * The {@link Charset} to encode the <code>String</code> 091 * @return the encoded bytes 092 */ 093 private static byte[] getBytes(final String string, final Charset charset) { 094 if (string == null) { 095 return null; 096 } 097 return string.getBytes(charset); 098 } 099 100 /** 101 * Calls {@link String#getBytes(Charset)} 102 * 103 * @param string 104 * The string to encode (if null, return null). 105 * @param charset 106 * The {@link Charset} to encode the <code>String</code> 107 * @return the encoded bytes 108 */ 109 private static ByteBuffer getByteBuffer(final String string, final Charset charset) { 110 if (string == null) { 111 return null; 112 } 113 return ByteBuffer.wrap(string.getBytes(charset)); 114 } 115 116 /** 117 * Encodes the given string into a byte buffer using the UTF-8 charset, storing the result into a new byte 118 * array. 119 * 120 * @param string 121 * the String to encode, may be <code>null</code> 122 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 123 * @throws NullPointerException 124 * Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is 125 * required by the Java platform specification. 126 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 127 * @see #getBytesUnchecked(String, String) 128 * @since 1.11 129 */ 130 public static ByteBuffer getByteBufferUtf8(final String string) { 131 return getByteBuffer(string, Charsets.UTF_8); 132 } 133 134 /** 135 * Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the result into a new 136 * byte array. 137 * 138 * @param string 139 * the String to encode, may be <code>null</code> 140 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 141 * @throws NullPointerException 142 * Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is 143 * required by the Java platform specification. 144 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 145 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 146 * @see #getBytesUnchecked(String, String) 147 */ 148 public static byte[] getBytesIso8859_1(final String string) { 149 return getBytes(string, Charsets.ISO_8859_1); 150 } 151 152 153 /** 154 * Encodes the given string into a sequence of bytes using the named charset, storing the result into a new byte 155 * array. 156 * <p> 157 * This method catches {@link UnsupportedEncodingException} and rethrows it as {@link IllegalStateException}, which 158 * should never happen for a required charset name. Use this method when the encoding is required to be in the JRE. 159 * </p> 160 * 161 * @param string 162 * the String to encode, may be <code>null</code> 163 * @param charsetName 164 * The name of a required {@link java.nio.charset.Charset} 165 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 166 * @throws IllegalStateException 167 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never happen for a 168 * required charset name. 169 * @see CharEncoding 170 * @see String#getBytes(String) 171 */ 172 public static byte[] getBytesUnchecked(final String string, final String charsetName) { 173 if (string == null) { 174 return null; 175 } 176 try { 177 return string.getBytes(charsetName); 178 } catch (final UnsupportedEncodingException e) { 179 throw StringUtils.newIllegalStateException(charsetName, e); 180 } 181 } 182 183 /** 184 * Encodes the given string into a sequence of bytes using the US-ASCII charset, storing the result into a new byte 185 * array. 186 * 187 * @param string 188 * the String to encode, may be <code>null</code> 189 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 190 * @throws NullPointerException 191 * Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is 192 * required by the Java platform specification. 193 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 194 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 195 * @see #getBytesUnchecked(String, String) 196 */ 197 public static byte[] getBytesUsAscii(final String string) { 198 return getBytes(string, Charsets.US_ASCII); 199 } 200 201 /** 202 * Encodes the given string into a sequence of bytes using the UTF-16 charset, storing the result into a new byte 203 * array. 204 * 205 * @param string 206 * the String to encode, may be <code>null</code> 207 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 208 * @throws NullPointerException 209 * Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is 210 * required by the Java platform specification. 211 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 212 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 213 * @see #getBytesUnchecked(String, String) 214 */ 215 public static byte[] getBytesUtf16(final String string) { 216 return getBytes(string, Charsets.UTF_16); 217 } 218 219 /** 220 * Encodes the given string into a sequence of bytes using the UTF-16BE charset, storing the result into a new byte 221 * array. 222 * 223 * @param string 224 * the String to encode, may be <code>null</code> 225 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 226 * @throws NullPointerException 227 * Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is 228 * required by the Java platform specification. 229 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 230 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 231 * @see #getBytesUnchecked(String, String) 232 */ 233 public static byte[] getBytesUtf16Be(final String string) { 234 return getBytes(string, Charsets.UTF_16BE); 235 } 236 237 /** 238 * Encodes the given string into a sequence of bytes using the UTF-16LE charset, storing the result into a new byte 239 * array. 240 * 241 * @param string 242 * the String to encode, may be <code>null</code> 243 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 244 * @throws NullPointerException 245 * Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is 246 * required by the Java platform specification. 247 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 248 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 249 * @see #getBytesUnchecked(String, String) 250 */ 251 public static byte[] getBytesUtf16Le(final String string) { 252 return getBytes(string, Charsets.UTF_16LE); 253 } 254 255 /** 256 * Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result into a new byte 257 * array. 258 * 259 * @param string 260 * the String to encode, may be <code>null</code> 261 * @return encoded bytes, or <code>null</code> if the input string was <code>null</code> 262 * @throws NullPointerException 263 * Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is 264 * required by the Java platform specification. 265 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 266 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 267 * @see #getBytesUnchecked(String, String) 268 */ 269 public static byte[] getBytesUtf8(final String string) { 270 return getBytes(string, Charsets.UTF_8); 271 } 272 273 private static IllegalStateException newIllegalStateException(final String charsetName, 274 final UnsupportedEncodingException e) { 275 return new IllegalStateException(charsetName + ": " + e); 276 } 277 278 /** 279 * Constructs a new <code>String</code> by decoding the specified array of bytes using the given charset. 280 * 281 * @param bytes 282 * The bytes to be decoded into characters 283 * @param charset 284 * The {@link Charset} to encode the <code>String</code>; not {@code null} 285 * @return A new <code>String</code> decoded from the specified array of bytes using the given charset, 286 * or <code>null</code> if the input byte array was <code>null</code>. 287 * @throws NullPointerException 288 * Thrown if charset is {@code null} 289 */ 290 private static String newString(final byte[] bytes, final Charset charset) { 291 return bytes == null ? null : new String(bytes, charset); 292 } 293 294 /** 295 * Constructs a new <code>String</code> by decoding the specified array of bytes using the given charset. 296 * <p> 297 * This method catches {@link UnsupportedEncodingException} and re-throws it as {@link IllegalStateException}, which 298 * should never happen for a required charset name. Use this method when the encoding is required to be in the JRE. 299 * </p> 300 * 301 * @param bytes 302 * The bytes to be decoded into characters, may be <code>null</code> 303 * @param charsetName 304 * The name of a required {@link java.nio.charset.Charset} 305 * @return A new <code>String</code> decoded from the specified array of bytes using the given charset, 306 * or <code>null</code> if the input byte array was <code>null</code>. 307 * @throws IllegalStateException 308 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never happen for a 309 * required charset name. 310 * @see CharEncoding 311 * @see String#String(byte[], String) 312 */ 313 public static String newString(final byte[] bytes, final String charsetName) { 314 if (bytes == null) { 315 return null; 316 } 317 try { 318 return new String(bytes, charsetName); 319 } catch (final UnsupportedEncodingException e) { 320 throw StringUtils.newIllegalStateException(charsetName, e); 321 } 322 } 323 324 /** 325 * Constructs a new <code>String</code> by decoding the specified array of bytes using the ISO-8859-1 charset. 326 * 327 * @param bytes 328 * The bytes to be decoded into characters, may be <code>null</code> 329 * @return A new <code>String</code> decoded from the specified array of bytes using the ISO-8859-1 charset, or 330 * <code>null</code> if the input byte array was <code>null</code>. 331 * @throws NullPointerException 332 * Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is 333 * required by the Java platform specification. 334 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 335 */ 336 public static String newStringIso8859_1(final byte[] bytes) { 337 return newString(bytes, Charsets.ISO_8859_1); 338 } 339 340 /** 341 * Constructs a new <code>String</code> by decoding the specified array of bytes using the US-ASCII charset. 342 * 343 * @param bytes 344 * The bytes to be decoded into characters 345 * @return A new <code>String</code> decoded from the specified array of bytes using the US-ASCII charset, 346 * or <code>null</code> if the input byte array was <code>null</code>. 347 * @throws NullPointerException 348 * Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is 349 * required by the Java platform specification. 350 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 351 */ 352 public static String newStringUsAscii(final byte[] bytes) { 353 return newString(bytes, Charsets.US_ASCII); 354 } 355 356 /** 357 * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16 charset. 358 * 359 * @param bytes 360 * The bytes to be decoded into characters 361 * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16 charset 362 * or <code>null</code> if the input byte array was <code>null</code>. 363 * @throws NullPointerException 364 * Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is 365 * required by the Java platform specification. 366 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 367 */ 368 public static String newStringUtf16(final byte[] bytes) { 369 return newString(bytes, Charsets.UTF_16); 370 } 371 372 /** 373 * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16BE charset. 374 * 375 * @param bytes 376 * The bytes to be decoded into characters 377 * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16BE charset, 378 * or <code>null</code> if the input byte array was <code>null</code>. 379 * @throws NullPointerException 380 * Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is 381 * required by the Java platform specification. 382 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 383 */ 384 public static String newStringUtf16Be(final byte[] bytes) { 385 return newString(bytes, Charsets.UTF_16BE); 386 } 387 388 /** 389 * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16LE charset. 390 * 391 * @param bytes 392 * The bytes to be decoded into characters 393 * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16LE charset, 394 * or <code>null</code> if the input byte array was <code>null</code>. 395 * @throws NullPointerException 396 * Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is 397 * required by the Java platform specification. 398 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 399 */ 400 public static String newStringUtf16Le(final byte[] bytes) { 401 return newString(bytes, Charsets.UTF_16LE); 402 } 403 404 /** 405 * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-8 charset. 406 * 407 * @param bytes 408 * The bytes to be decoded into characters 409 * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-8 charset, 410 * or <code>null</code> if the input byte array was <code>null</code>. 411 * @throws NullPointerException 412 * Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is 413 * required by the Java platform specification. 414 * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException 415 */ 416 public static String newStringUtf8(final byte[] bytes) { 417 return newString(bytes, Charsets.UTF_8); 418 } 419 420}