Class BaseEncoding
- java.lang.Object
-
- com.google.common.io.BaseEncoding
-
@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==="
, andbyte[] 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 tox
, but the reverse does not necessarily hold.Encodings Encoding Alphabet char:byte
ratioDefault 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
- Author:
- Louis Wasserman
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
BaseEncoding.DecodingException
Exception indicating invalid base-encoded input encountered while decoding.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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.)abstract boolean
canDecode(java.lang.CharSequence chars)
Determines whether the specified character sequence is a valid encoded string according to this encoding.byte[]
decode(java.lang.CharSequence chars)
Decodes the specified character sequence, and returns the resultingbyte[]
.ByteSource
decodingSource(CharSource encodedSource)
Returns aByteSource
that reads base-encoded bytes from the specifiedCharSource
.abstract java.io.InputStream
decodingStream(java.io.Reader reader)
Returns anInputStream
that decodes base-encoded input from the specifiedReader
.java.lang.String
encode(byte[] bytes)
Encodes the specified byte array, and returns the encodedString
.java.lang.String
encode(byte[] bytes, int off, int len)
Encodes the specified range of the specified byte array, and returns the encodedString
.ByteSink
encodingSink(CharSink encodedSink)
Returns aByteSink
that writes base-encoded bytes to the specifiedCharSink
.abstract java.io.OutputStream
encodingStream(java.io.Writer writer)
Returns anOutputStream
that encodes bytes using this encoding into the specifiedWriter
.abstract BaseEncoding
ignoreCase()
Returns an encoding that behaves equivalently to this encoding, but decodes letters without regard to case.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 everyn
characters.
-
-
-
Method Detail
-
encode
public java.lang.String encode(byte[] bytes)
Encodes the specified byte array, and returns the encodedString
.
-
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 encodedString
.
-
encodingStream
@GwtIncompatible public abstract java.io.OutputStream encodingStream(java.io.Writer writer)
Returns anOutputStream
that encodes bytes using this encoding into the specifiedWriter
. When the returnedOutputStream
is closed, so is the backingWriter
.
-
encodingSink
@GwtIncompatible public final ByteSink encodingSink(CharSink encodedSink)
Returns aByteSink
that writes base-encoded bytes to the specifiedCharSink
.
-
canDecode
public abstract boolean canDecode(java.lang.CharSequence chars)
Determines whether the specified character sequence is a valid encoded string according to this encoding.- Since:
- 20.0
-
decode
public final byte[] decode(java.lang.CharSequence chars)
Decodes the specified character sequence, and returns the resultingbyte[]
. This is the inverse operation toencode(byte[])
.- Throws:
java.lang.IllegalArgumentException
- if the input is not a valid encoded string according to this encoding.
-
decodingStream
@GwtIncompatible public abstract java.io.InputStream decodingStream(java.io.Reader reader)
Returns anInputStream
that decodes base-encoded input from the specifiedReader
. The returned stream throws aBaseEncoding.DecodingException
upon decoding-specific errors.
-
decodingSource
@GwtIncompatible public final ByteSource decodingSource(CharSource encodedSource)
Returns aByteSource
that reads base-encoded bytes from the specifiedCharSource
.
-
omitPadding
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
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
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 everyn
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 ifn <= 0
java.lang.UnsupportedOperationException
- if this encoding already uses a separator
-
upperCase
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
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
-
ignoreCase
public abstract BaseEncoding ignoreCase()
Returns an encoding that behaves equivalently to this encoding, but decodes letters without regard to case.- Throws:
java.lang.IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and lower-case characters- Since:
- 32.0.0
-
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)
andomitPadding()
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)
.
-
-