/*

  * Licensed to the Apache Software Foundation (ASF) under one or more

  * contributor license agreements.  See the NOTICE file distributed with

  * this work for additional information regarding copyright ownership.

  * The ASF licenses this file to You 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 org.apache.commons.codec.binary;

 import java.io.UnsupportedEncodingException;

 import java.nio.charset.Charset;

 import org.apache.commons.codec.CharEncoding;

 import org.apache.commons.codec.Charsets;

 /**

  * Converts String to and from bytes using the encodings required by the Java specification. These encodings are

  * specified in <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">

  * Standard charsets</a>.

  *

  * <p>This class is immutable and thread-safe.</p>

  *

  * @see CharEncoding

  * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

  * @version $Id$

  * @since 1.4

  */

 public class StringUtils {

     /**

      * Calls {@link String#getBytes(Charset)}

      *

      * @param string

      *            The string to encode (if null, return null).

      * @param charset

      *            The {@link Charset} to encode the {@code String}

      * @return the encoded bytes

      */

     private static byte[] getBytes(String string, Charset charset) {

         if (string == null) {

             return null;

         }

         return string.getBytes(charset);

     }

     /**

      * Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the result into a new

      * byte array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesIso8859_1(String string) {

         return getBytes(string, Charsets.ISO_8859_1);

     }

     /**

      * Encodes the given string into a sequence of bytes using the named charset, storing the result into a new byte

      * array.

      * <p>

      * This method catches {@link UnsupportedEncodingException} and rethrows it as {@link IllegalStateException}, which

      * should never happen for a required charset name. Use this method when the encoding is required to be in the JRE.

      * </p>

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @param charsetName

      *            The name of a required {@link java.nio.charset.Charset}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws IllegalStateException

      *             Thrown when a {@link UnsupportedEncodingException} is caught, which should never happen for a

      *             required charset name.

      * @see CharEncoding

      * @see String#getBytes(String)

      */

     public static byte[] getBytesUnchecked(String string, String charsetName) {

         if (string == null) {

             return null;

         }

         try {

             return string.getBytes(charsetName);

         } catch (UnsupportedEncodingException e) {

             throw StringUtils.newIllegalStateException(charsetName, e);

         }

     }

     /**

      * Encodes the given string into a sequence of bytes using the US-ASCII charset, storing the result into a new byte

      * array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesUsAscii(String string) {

         return getBytes(string, Charsets.US_ASCII);

     }

     /**

      * Encodes the given string into a sequence of bytes using the UTF-16 charset, storing the result into a new byte

      * array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesUtf16(String string) {

         return getBytes(string, Charsets.UTF_16);

     }

     /**

      * Encodes the given string into a sequence of bytes using the UTF-16BE charset, storing the result into a new byte

      * array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesUtf16Be(String string) {

         return getBytes(string, Charsets.UTF_16BE);

     }

     /**

      * Encodes the given string into a sequence of bytes using the UTF-16LE charset, storing the result into a new byte

      * array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesUtf16Le(String string) {

         return getBytes(string, Charsets.UTF_16LE);

     }

     /**

      * Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result into a new byte

      * array.

      *

      * @param string

      *            the String to encode, may be {@code null}

      * @return encoded bytes, or {@code null} if the input string was {@code null}

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>

      * @see #getBytesUnchecked(String, String)

      */

     public static byte[] getBytesUtf8(String string) {

         return getBytes(string, Charsets.UTF_8);

     }

     private static IllegalStateException newIllegalStateException(String charsetName, UnsupportedEncodingException e) {

         return new IllegalStateException(charsetName + ": " + e);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the given charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @param charset

      *            The {@link Charset} to encode the {@code String}

      * @return A new <code>String</code> decoded from the specified array of bytes using the given charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      */

     private static String newString(byte[] bytes, Charset charset) {

         return bytes == null ? null : new String(bytes, charset);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the given charset.

      * <p>

      * This method catches {@link UnsupportedEncodingException} and re-throws it as {@link IllegalStateException}, which

      * should never happen for a required charset name. Use this method when the encoding is required to be in the JRE.

      * </p>

      *

      * @param bytes

      *            The bytes to be decoded into characters, may be {@code null}

      * @param charsetName

      *            The name of a required {@link java.nio.charset.Charset}

      * @return A new <code>String</code> decoded from the specified array of bytes using the given charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws IllegalStateException

      *             Thrown when a {@link UnsupportedEncodingException} is caught, which should never happen for a

      *             required charset name.

      * @see CharEncoding

      * @see String#String(byte[], String)

      */

     public static String newString(byte[] bytes, String charsetName) {

         if (bytes == null) {

             return null;

         }

         try {

             return new String(bytes, charsetName);

         } catch (UnsupportedEncodingException e) {

             throw StringUtils.newIllegalStateException(charsetName, e);

         }

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the ISO-8859-1 charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters, may be {@code null}

      * @return A new <code>String</code> decoded from the specified array of bytes using the ISO-8859-1 charset, or

      *         {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringIso8859_1(byte[] bytes) {

         return new String(bytes, Charsets.ISO_8859_1);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the US-ASCII charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @return A new <code>String</code> decoded from the specified array of bytes using the US-ASCII charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringUsAscii(byte[] bytes) {

         return new String(bytes, Charsets.US_ASCII);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16 charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16 charset

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringUtf16(byte[] bytes) {

         return new String(bytes, Charsets.UTF_16);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16BE charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16BE charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringUtf16Be(byte[] bytes) {

         return new String(bytes, Charsets.UTF_16BE);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-16LE charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-16LE charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringUtf16Le(byte[] bytes) {

         return new String(bytes, Charsets.UTF_16LE);

     }

     /**

      * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-8 charset.

      *

      * @param bytes

      *            The bytes to be decoded into characters

      * @return A new <code>String</code> decoded from the specified array of bytes using the UTF-8 charset,

      *         or {@code null} if the input byte array was {@code null}.

      * @throws NullPointerException

      *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is

      *             required by the Java platform specification.

      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException

      */

     public static String newStringUtf8(byte[] bytes) {

         return newString(bytes, Charsets.UTF_8);

     }

 }