BaseEncoding
Date: 2016-05-24

com.google.common.io

## Class BaseEncoding

- java.lang.Object
- - com.google.common.io.BaseEncoding

-     @Beta
      @GwtCompatible(emulated=true)
      public abstract class BaseEncoding
      extends java.lang.Object

  A binary encoding scheme for reversibly translating between byte sequences and printable ASCII strings. This class includes several constants for encoding schemes specified by RFC 4648. For example, the expression:

         BaseEncoding.base32().encode("foo".getBytes(Charsets.US_ASCII))

  returns the string `"MZXW6==="`, and

         byte[] decoded = BaseEncoding.base32().decode("MZXW6===");

  ...returns the ASCII bytes of the string `"foo"`.

  By default, `BaseEncoding`'s behavior is relatively strict and in accordance with RFC 4648. Decoding rejects characters in the wrong case, though padding is optional. To modify encoding and decoding behavior, use configuration methods to obtain a new encoding with modified behavior:

         BaseEncoding.base16().lowerCase().decode("deadbeef");

  Warning: BaseEncoding instances are immutable. Invoking a configuration method has no effect on the receiving instance; you must store and use the new encoding instance it returns, instead.

         // Do NOT do this
         BaseEncoding hex = BaseEncoding.base16();
         hex.lowerCase(); // does nothing!
         return hex.decode("deadbeef"); // throws an IllegalArgumentException

  It is guaranteed that `encoding.decode(encoding.encode(x))` is always equal to `x`, but the reverse does not necessarily hold.

  Encoding | Alphabet | `char:byte` ratio | Default padding | Comments
  --- | --- | --- | --- | ---
  `base16()` | 0-9 A-F | 2.00 | N/A | Traditional hexadecimal. Defaults to upper case.
  `base32()` | A-Z 2-7 | 1.60 | = | Human-readable; no possibility of mixing up 0/O or 1/I. Defaults to upper case.
  `base32Hex()` | 0-9 A-V | 1.60 | = | "Numerical" base 32; extended from the traditional hex alphabet. Defaults to upper case.
  `base64()` | A-Z a-z 0-9 + / | 1.33 | = |
  `base64Url()` | A-Z a-z 0-9 - _ | 1.33 | = | Safe to use as filenames, or to pass in URLs without escaping

  All instances of this class are immutable, so they may be stored safely as static constants.

  Since:
    14.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `BaseEncoding.DecodingException` Exception indicating invalid base-encoded input encountered while decoding.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static BaseEncoding` | `base16()` The "base16" encoding specified by RFC 4648 section 8, Base 16 Encoding.
    `static BaseEncoding` | `base32()` The "base32" encoding specified by RFC 4648 section 6, Base 32 Encoding.
    `static BaseEncoding` | `base32Hex()` The "base32hex" encoding specified by RFC 4648 section 7, Base 32 Encoding with Extended Hex Alphabet.
    `static BaseEncoding` | `base64()` The "base64" base encoding specified by RFC 4648 section 4, Base 64 Encoding.
    `static BaseEncoding` | `base64Url()` The "base64url" encoding specified by RFC 4648 section 5, Base 64 Encoding with URL and Filename Safe Alphabet, also sometimes referred to as the "web safe Base64." (This is the same as the base 64 encoding with URL and filename safe alphabet from RFC 3548.)
    `byte[]` | `decode(java.lang.CharSequence chars)` Decodes the specified character sequence, and returns the resulting `byte[]`.
    `ByteSource` | `decodingSource(CharSource encodedSource)` Returns a `ByteSource` that reads base-encoded bytes from the specified `CharSource`.
    `abstract java.io.InputStream` | `decodingStream(java.io.Reader reader)` Returns an `InputStream` that decodes base-encoded input from the specified `Reader`.
    `java.lang.String` | `encode(byte[] bytes)` Encodes the specified byte array, and returns the encoded `String`.
    `java.lang.String` | `encode(byte[] bytes, int off, int len)` Encodes the specified range of the specified byte array, and returns the encoded `String`.
    `ByteSink` | `encodingSink(CharSink encodedSink)` Returns a `ByteSink` that writes base-encoded bytes to the specified `CharSink`.
    `abstract java.io.OutputStream` | `encodingStream(java.io.Writer writer)` Returns an `OutputStream` that encodes bytes using this encoding into the specified `Writer`.
    `abstract BaseEncoding` | `lowerCase()` Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with lowercase letters.
    `abstract BaseEncoding` | `omitPadding()` Returns an encoding that behaves equivalently to this encoding, but omits any padding characters as specified by RFC 4648 section 3.2, Padding of Encoded Data.
    `abstract BaseEncoding` | `upperCase()` Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with uppercase letters.
    `abstract BaseEncoding` | `withPadChar(char padChar)` Returns an encoding that behaves equivalently to this encoding, but uses an alternate character for padding.
    `abstract BaseEncoding` | `withSeparator(java.lang.String separator, int n)` Returns an encoding that behaves equivalently to this encoding, but adds a separator string after every `n` characters.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### encode

          public java.lang.String encode(byte[] bytes)

      Encodes the specified byte array, and returns the encoded `String`.

    - #### encode

          public final java.lang.String encode(byte[] bytes,
                                int off,
                                int len)

      Encodes the specified range of the specified byte array, and returns the encoded `String`.

    - #### encodingStream

          @GwtIncompatible(value="Writer,OutputStream")
          public abstract java.io.OutputStream encodingStream(java.io.Writer writer)

      Returns an `OutputStream` that encodes bytes using this encoding into the specified `Writer`. When the returned `OutputStream` is closed, so is the backing `Writer`.

    - #### encodingSink

          @GwtIncompatible(value="ByteSink,CharSink")
          public final ByteSink encodingSink(CharSink encodedSink)

      Returns a `ByteSink` that writes base-encoded bytes to the specified `CharSink`.

    - #### decode

          public final byte[] decode(java.lang.CharSequence chars)

      Decodes the specified character sequence, and returns the resulting `byte[]`. This is the inverse operation to `encode(byte[])`.
      Throws:
        `java.lang.IllegalArgumentException` - if the input is not a valid encoded string according to this encoding.

    - #### decodingStream

          @GwtIncompatible(value="Reader,InputStream")
          public abstract java.io.InputStream decodingStream(java.io.Reader reader)

      Returns an `InputStream` that decodes base-encoded input from the specified `Reader`. The returned stream throws a `BaseEncoding.DecodingException` upon decoding-specific errors.

    - #### decodingSource

          @GwtIncompatible(value="ByteSource,CharSource")
          public final ByteSource decodingSource(CharSource encodedSource)

      Returns a `ByteSource` that reads base-encoded bytes from the specified `CharSource`.

    - #### omitPadding

          @CheckReturnValue
          public abstract BaseEncoding omitPadding()

      Returns an encoding that behaves equivalently to this encoding, but omits any padding characters as specified by RFC 4648 section 3.2, Padding of Encoded Data.

    - #### withPadChar

          @CheckReturnValue
          public abstract BaseEncoding withPadChar(char padChar)

      Returns an encoding that behaves equivalently to this encoding, but uses an alternate character for padding.
      Throws:
        `java.lang.IllegalArgumentException` - if this padding character is already used in the alphabet or a separator

    - #### withSeparator

          @CheckReturnValue
          public abstract BaseEncoding withSeparator(java.lang.String separator,
                                                    int n)

      Returns an encoding that behaves equivalently to this encoding, but adds a separator string after every `n` characters. Any occurrences of any characters that occur in the separator are skipped over in decoding.
      Throws:
        `java.lang.IllegalArgumentException` - if any alphabet or padding characters appear in the separator string, or if `n <= 0`
        `java.lang.UnsupportedOperationException` - if this encoding already uses a separator

    - #### upperCase

          @CheckReturnValue
          public abstract BaseEncoding upperCase()

      Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with uppercase letters. Padding and separator characters remain in their original case.
      Throws:
        `java.lang.IllegalStateException` - if the alphabet used by this encoding contains mixed upper- and lower-case characters

    - #### lowerCase

          @CheckReturnValue
          public abstract BaseEncoding lowerCase()

      Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with lowercase letters. Padding and separator characters remain in their original case.
      Throws:
        `java.lang.IllegalStateException` - if the alphabet used by this encoding contains mixed upper- and lower-case characters

    - #### base64

          public static BaseEncoding base64()

      The "base64" base encoding specified by RFC 4648 section 4, Base 64 Encoding. (This is the same as the base 64 encoding from RFC 3548.)

      The character `'='` is used for padding, but can be omitted or replaced.

      No line feeds are added by default, as per RFC 4648 section 3.1, Line Feeds in Encoded Data. Line feeds may be added using `withSeparator(String, int)`.

    - #### base64Url

          public static BaseEncoding base64Url()

      The "base64url" encoding specified by RFC 4648 section 5, Base 64 Encoding with URL and Filename Safe Alphabet, also sometimes referred to as the "web safe Base64." (This is the same as the base 64 encoding with URL and filename safe alphabet from RFC 3548.)

      The character `'='` is used for padding, but can be omitted or replaced.

      No line feeds are added by default, as per RFC 4648 section 3.1, Line Feeds in Encoded Data. Line feeds may be added using `withSeparator(String, int)`.

    - #### base32

          public static BaseEncoding base32()

      The "base32" encoding specified by RFC 4648 section 6, Base 32 Encoding. (This is the same as the base 32 encoding from RFC 3548.)

      The character `'='` is used for padding, but can be omitted or replaced.

      No line feeds are added by default, as per RFC 4648 section 3.1, Line Feeds in Encoded Data. Line feeds may be added using `withSeparator(String, int)`.

    - #### base32Hex

          public static BaseEncoding base32Hex()

      The "base32hex" encoding specified by RFC 4648 section 7, Base 32 Encoding with Extended Hex Alphabet. There is no corresponding encoding in RFC 3548.

      The character `'='` is used for padding, but can be omitted or replaced.

      No line feeds are added by default, as per RFC 4648 section 3.1, Line Feeds in Encoded Data. Line feeds may be added using `withSeparator(String, int)`.

    - #### base16

          public static BaseEncoding base16()

      The "base16" encoding specified by RFC 4648 section 8, Base 16 Encoding. (This is the same as the base 16 encoding from RFC 3548.) This is commonly known as "hexadecimal" format.

      No padding is necessary in base 16, so `withPadChar(char)` and `omitPadding()` have no effect.

      No line feeds are added by default, as per RFC 4648 section 3.1, Line Feeds in Encoded Data. Line feeds may be added using `withSeparator(String, int)`.