Class BaseEncoding
- Direct Known Subclasses:
BaseEncoding.SeparatedBaseEncoding
,BaseEncoding.StandardBaseEncoding
BaseEncoding.base32().encode("foo".getBytes(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 ClassesModifier and TypeClassDescription(package private) static final class
private static final class
private static final class
static final class
Exception indicating invalid base-encoded input encountered while decoding.(package private) static final class
private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final BaseEncoding
private static final BaseEncoding
private static final BaseEncoding
private static final BaseEncoding
private static final BaseEncoding
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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
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
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
(CharSequence chars) Determines whether the specified character sequence is a valid encoded string according to this encoding.final byte[]
decode
(CharSequence chars) Decodes the specified character sequence, and returns the resultingbyte[]
.(package private) final byte[]
decodeChecked
(CharSequence chars) Decodes the specified character sequence, and returns the resultingbyte[]
.(package private) abstract int
decodeTo
(byte[] target, CharSequence chars) final ByteSource
decodingSource
(CharSource encodedSource) Returns aByteSource
that reads base-encoded bytes from the specifiedCharSource
.abstract InputStream
decodingStream
(Reader reader) Returns anInputStream
that decodes base-encoded input from the specifiedReader
.encode
(byte[] bytes) Encodes the specified byte array, and returns the encodedString
.final String
encode
(byte[] bytes, int off, int len) Encodes the specified range of the specified byte array, and returns the encodedString
.(package private) abstract void
encodeTo
(Appendable target, byte[] bytes, int off, int len) final ByteSink
encodingSink
(CharSink encodedSink) Returns aByteSink
that writes base-encoded bytes to the specifiedCharSink
.abstract OutputStream
encodingStream
(Writer writer) Returns anOutputStream
that encodes bytes using this encoding into the specifiedWriter
.private static byte[]
extract
(byte[] result, int length) abstract BaseEncoding
Returns an encoding that behaves equivalently to this encoding, but decodes letters without regard to case.(package private) static Reader
ignoringReader
(Reader delegate, String toIgnore) abstract BaseEncoding
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
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) static Appendable
separatingAppendable
(Appendable delegate, String separator, int afterEveryChars) (package private) static Writer
separatingWriter
(Writer delegate, String separator, int afterEveryChars) (package private) CharSequence
trimTrailingPadding
(CharSequence chars) abstract BaseEncoding
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
(String separator, int n) Returns an encoding that behaves equivalently to this encoding, but adds a separator string after everyn
characters.
-
Field Details
-
BASE64
-
BASE64_URL
-
BASE32
-
BASE32_HEX
-
BASE16
-
-
Constructor Details
-
BaseEncoding
BaseEncoding()
-
-
Method Details
-
encode
Encodes the specified byte array, and returns the encodedString
. -
encode
Encodes the specified range of the specified byte array, and returns the encodedString
. -
encodingStream
Returns anOutputStream
that encodes bytes using this encoding into the specifiedWriter
. When the returnedOutputStream
is closed, so is the backingWriter
. -
encodingSink
Returns aByteSink
that writes base-encoded bytes to the specifiedCharSink
. -
extract
private static byte[] extract(byte[] result, int length) -
canDecode
Determines whether the specified character sequence is a valid encoded string according to this encoding.- Since:
- 20.0
-
decode
Decodes the specified character sequence, and returns the resultingbyte[]
. This is the inverse operation toencode(byte[])
.- Throws:
IllegalArgumentException
- if the input is not a valid encoded string according to this encoding.
-
decodeChecked
Decodes the specified character sequence, and returns the resultingbyte[]
. This is the inverse operation toencode(byte[])
.- Throws:
BaseEncoding.DecodingException
- if the input is not a valid encoded string according to this encoding.
-
decodingStream
Returns anInputStream
that decodes base-encoded input from the specifiedReader
. The returned stream throws aBaseEncoding.DecodingException
upon decoding-specific errors. -
decodingSource
Returns aByteSource
that reads base-encoded bytes from the specifiedCharSource
. -
maxEncodedSize
abstract int maxEncodedSize(int bytes) -
encodeTo
- Throws:
IOException
-
maxDecodedSize
abstract int maxDecodedSize(int chars) -
decodeTo
- Throws:
BaseEncoding.DecodingException
-
trimTrailingPadding
-
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
Returns an encoding that behaves equivalently to this encoding, but uses an alternate character for padding.- Throws:
IllegalArgumentException
- if this padding character is already used in the alphabet or a separator
-
withSeparator
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:
IllegalArgumentException
- if any alphabet or padding characters appear in the separator string, or ifn <= 0
UnsupportedOperationException
- if this encoding already uses a separator
-
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:
IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and lower-case characters
-
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:
IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and lower-case characters
-
ignoreCase
Returns an encoding that behaves equivalently to this encoding, but decodes letters without regard to case.- Throws:
IllegalStateException
- if the alphabet used by this encoding contains mixed upper- and lower-case characters- Since:
- 32.0.0
-
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
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
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
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
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)
. -
ignoringReader
-
separatingAppendable
-
separatingWriter
-