Expand description
Configs
There isn’t just one type of Base64; that would be too simple. You need to choose a character
set (standard, URL-safe, etc) and padding suffix (yes/no).
The Config struct encapsulates this info. There are some common configs included: STANDARD,
URL_SAFE, etc. You can also make your own Config if needed.
The functions that don’t have config in the name (e.g. encode() and decode()) use the
STANDARD config .
The functions that write to a slice (the ones that end in _slice) are generally the fastest
because they don’t need to resize anything. If it fits in your workflow and you care about
performance, keep using the same buffer (growing as need be) and use the _slice methods for
the best performance.
Encoding
Several different encoding functions are available to you depending on your desire for convenience vs performance.
| Function | Output | Allocates |
|---|---|---|
encode | Returns a new String | Always |
encode_config | Returns a new String | Always |
encode_config_buf | Appends to provided String | Only if String needs to grow |
encode_config_slice | Writes to provided &[u8] | Never |
All of the encoding functions that take a Config will pad as per the config.
Decoding
Just as for encoding, there are different decoding functions available.
| Function | Output | Allocates |
|---|---|---|
decode | Returns a new Vec<u8> | Always |
decode_config | Returns a new Vec<u8> | Always |
decode_config_buf | Appends to provided Vec<u8> | Only if Vec needs to grow |
decode_config_slice | Writes to provided &[u8] | Never |
Unlike encoding, where all possible input is valid, decoding can fail (see DecodeError).
Input can be invalid because it has invalid characters or invalid padding. (No padding at all is valid, but excess padding is not.) Whitespace in the input is invalid.
Read and Write
To map a Read of b64 bytes to the decoded bytes, wrap a reader (file, network socket, etc)
with base64::read::DecoderReader. To write raw bytes and have them b64 encoded on the fly,
wrap a writer with base64::write::EncoderWriter. There is some performance overhead (15% or
so) because of the necessary buffer shuffling – still fast enough that almost nobody cares.
Also, these implementations do not heap allocate.
Panics
If length calculations result in overflowing usize, a panic will result.
The _slice flavors of encode or decode will panic if the provided output slice is too small,
Modules
Enables base64’d output anywhere you might use a Display implementation, like a format string.
Implementations of io::Read to transparently decode base64.
Implementations of io::Write to transparently handle base64.
Structs
Contains configuration parameters for base64 encoding
Enums
Available encoding character sets
Errors that can occur while decoding.
Constants
Bcrypt character set
BinHex character set
As per crypt(3) requirements
IMAP modified UTF-7 requirements
Standard character set with padding.
Standard character set without padding.
URL-safe character set with padding
URL-safe character set without padding
Functions
Decode from string reference as octets.
Returns a Result containing a Vecdecode_config(input, base64::STANDARD);.
Decode from string reference as octets.
Returns a Result containing a Vec
Decode from string reference as octets. Writes into the supplied buffer to avoid allocation. Returns a Result containing an empty tuple, aka ().
Decode the input into the provided output slice.
Encode arbitrary octets as base64.
Returns a String.
Convenience for encode_config(input, base64::STANDARD);.
Encode arbitrary octets as base64. Returns a String.
Encode arbitrary octets as base64. Writes into the supplied output buffer, which will grow the buffer if needed.
Encode arbitrary octets as base64. Writes into the supplied output buffer.