- Description
- Nested Class Summary
- Method Summary
- Method Details
- encode(byte[])
- encode(byte[], int, int)
- encodingStream(Writer)
- encodingSink(CharSink)
- canDecode(CharSequence)
- decode(CharSequence)
- decodingStream(Reader)
- decodingSource(CharSource)
- omitPadding()
- withPadChar(char)
- withSeparator(String, int)
- upperCase()
- lowerCase()
- ignoreCase()
- base64()
- base64Url()
- base32()
- base32Hex()
- base16()
Class BaseEncoding
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
- Author:
- Louis Wasserman
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Exception indicating invalid base-encoded input encountered while decoding. -
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."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[]
.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
.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
.abstract BaseEncoding
Returns an encoding that behaves equivalently to this encoding, but decodes letters without regard to case.abstract BaseEncoding
Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with lowercase letters.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.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.
-
Method Details
-
encode
-
encode
-
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
. -
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.
-
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
. -
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)
.
-