# Crate base64

source · [−]
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

display

Enables base64’d output anywhere you might use a `Display` implementation, like a format string.

read

Implementations of `io::Read` to transparently decode base64.

write

Implementations of `io::Write` to transparently handle base64.

## Structs

Config

Contains configuration parameters for base64 encoding

## Enums

CharacterSet

Available encoding character sets

DecodeError

Errors that can occur while decoding.

## Constants

BCRYPT

Bcrypt character set

BINHEX

BinHex character set

CRYPT

As per `crypt(3)` requirements

IMAP_MUTF7

IMAP modified UTF-7 requirements

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<u8>. Convenience `decode_config(input, base64::STANDARD);`.

decode_config

Decode from string reference as octets. Returns a Result containing a Vec<u8>.

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.