@Beta @GwtCompatible(emulated=true) public abstract class BaseEncoding extends java.lang.Object
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.
Modifier and Type | Class and Description |
---|---|
private static class |
BaseEncoding.Alphabet |
static class |
BaseEncoding.DecodingException
Exception indicating invalid base-encoded input encountered while decoding.
|
(package private) static class |
BaseEncoding.SeparatedBaseEncoding |
(package private) static class |
BaseEncoding.StandardBaseEncoding |
Modifier and Type | Field and Description |
---|---|
private static BaseEncoding |
BASE16 |
private static BaseEncoding |
BASE32 |
private static BaseEncoding |
BASE32_HEX |
private static BaseEncoding |
BASE64 |
private static BaseEncoding |
BASE64_URL |
Constructor and Description |
---|
BaseEncoding() |
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[] . |
(package private) byte[] |
decodeChecked(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 . |
(package private) abstract GwtWorkarounds.ByteInput |
decodingStream(GwtWorkarounds.CharInput charInput) |
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 . |
(package private) abstract GwtWorkarounds.ByteOutput |
encodingStream(GwtWorkarounds.CharOutput charOutput) |
java.io.OutputStream |
encodingStream(java.io.Writer writer)
Returns an
OutputStream that encodes bytes using this encoding into the specified
Writer . |
private static byte[] |
extract(byte[] result,
int length) |
(package private) static GwtWorkarounds.CharInput |
ignoringInput(GwtWorkarounds.CharInput delegate,
CharMatcher toIgnore) |
abstract BaseEncoding |
lowerCase()
Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with
lowercase letters.
|
(package private) abstract int |
maxDecodedSize(int chars) |
(package private) abstract int |
maxEncodedSize(int bytes) |
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.
|
(package private) abstract CharMatcher |
padding() |
(package private) static GwtWorkarounds.CharOutput |
separatingOutput(GwtWorkarounds.CharOutput delegate,
java.lang.String separator,
int afterEveryChars) |
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. |
private static final BaseEncoding BASE64
private static final BaseEncoding BASE64_URL
private static final BaseEncoding BASE32
private static final BaseEncoding BASE32_HEX
private static final BaseEncoding BASE16
public java.lang.String encode(byte[] bytes)
String
.public final java.lang.String encode(byte[] bytes, int off, int len)
String
.@GwtIncompatible(value="Writer,OutputStream") public final java.io.OutputStream encodingStream(java.io.Writer writer)
OutputStream
that encodes bytes using this encoding into the specified
Writer
. When the returned OutputStream
is closed, so is the backing
Writer
.@GwtIncompatible(value="ByteSink,CharSink") public final ByteSink encodingSink(CharSink encodedSink)
ByteSink
that writes base-encoded bytes to the specified CharSink
.private static byte[] extract(byte[] result, int length)
public final byte[] decode(java.lang.CharSequence chars)
byte[]
.
This is the inverse operation to encode(byte[])
.java.lang.IllegalArgumentException
- if the input is not a valid encoded string according to this
encoding.final byte[] decodeChecked(java.lang.CharSequence chars) throws BaseEncoding.DecodingException
byte[]
.
This is the inverse operation to encode(byte[])
.BaseEncoding.DecodingException
- if the input is not a valid encoded string according to this
encoding.@GwtIncompatible(value="Reader,InputStream") public final java.io.InputStream decodingStream(java.io.Reader reader)
InputStream
that decodes base-encoded input from the specified
Reader
. The returned stream throws a BaseEncoding.DecodingException
upon decoding-specific
errors.@GwtIncompatible(value="ByteSource,CharSource") public final ByteSource decodingSource(CharSource encodedSource)
ByteSource
that reads base-encoded bytes from the specified
CharSource
.abstract int maxEncodedSize(int bytes)
abstract GwtWorkarounds.ByteOutput encodingStream(GwtWorkarounds.CharOutput charOutput)
abstract int maxDecodedSize(int chars)
abstract GwtWorkarounds.ByteInput decodingStream(GwtWorkarounds.CharInput charInput)
abstract CharMatcher padding()
@CheckReturnValue public abstract BaseEncoding omitPadding()
@CheckReturnValue public abstract BaseEncoding withPadChar(char padChar)
java.lang.IllegalArgumentException
- if this padding character is already used in the alphabet or a
separator@CheckReturnValue public abstract BaseEncoding withSeparator(java.lang.String separator, int n)
n
characters. Any occurrences of any characters that occur in the separator
are skipped over in decoding.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@CheckReturnValue public abstract BaseEncoding upperCase()
java.lang.IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and
lower-case characters@CheckReturnValue public abstract BaseEncoding lowerCase()
java.lang.IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and
lower-case characterspublic static BaseEncoding base64()
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)
.
public static BaseEncoding base64Url()
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)
.
public static BaseEncoding base32()
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)
.
public static BaseEncoding base32Hex()
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)
.
public static BaseEncoding base16()
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)
.
static GwtWorkarounds.CharInput ignoringInput(GwtWorkarounds.CharInput delegate, CharMatcher toIgnore)
static GwtWorkarounds.CharOutput separatingOutput(GwtWorkarounds.CharOutput delegate, java.lang.String separator, int afterEveryChars)