Crate base64 [−] [src]

Configs

There isn't just one type of Base64; that would be too simple. You need to choose a character set (standard or URL-safe), padding suffix (yes/no), and line wrap (line length, line ending). The Config struct encapsulates this info. There are some common configs included: STANDARD, MIME, 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, line wrap, etc, as per the config.

Decoding

Just as for encoding, there are different decoding functions available.

Note that all decode functions that take a config will allocate a copy of the input if you specify a config that requires whitespace to be stripped. If you care about speed, don't use formats that line wrap and then require whitespace stripping.

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 unless strip_whitespace is enabled in the Config used.

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,

CharacterSet	Available encoding character sets
DecodeError	Errors that can occur while decoding.
LineEnding	Line ending used in optional line wrapping.
LineWrap	Line wrap configuration.

Constants

CRYPT	As per `crypt(3)` requirements
MIME	As per standards for MIME encoded messages
STANDARD	Standard character set with padding.
STANDARD_NO_PAD	Standard character set without padding.
URL_SAFE	URL-safe character set with padding
URL_SAFE_NO_PAD	URL-safe character set without padding

Functions

decode	Decode from string reference as octets. Returns a Result containing a Vec. Convenience `decode_config(input, base64::STANDARD);`.
decode_config	Decode from string reference as octets. Returns a Result containing a Vec.
decode_config_buf	Decode from string reference as octets. Writes into the supplied buffer to avoid allocation. Returns a Result containing an empty tuple, aka ().
decode_config_slice	Decode the input into the provided output slice.
encode	Encode arbitrary octets as base64. Returns a String. Convenience for `encode_config(input, base64::STANDARD);`.
encode_config	Encode arbitrary octets as base64. Returns a String.
encode_config_buf	Encode arbitrary octets as base64. Writes into the supplied output buffer, which will grow the buffer if needed.
encode_config_slice	Encode arbitrary octets as base64. Writes into the supplied output buffer.