impl Encoding

fn encode_len(&self, len: usize) -> usize

Returns the encoded length of an input of length len

See encode_mut for when to use it.

Panics

May panic if len is greater than usize::MAX / 512:

• len <= 8_388_607 when target_pointer_width = "32"
• len <= 36028_797018_963967 when target_pointer_width = "64"

If you need to encode an input of length greater than this limit (possibly of infinite length), then you must chunk your input, encode each chunk, and concatenate to obtain the output. The length of each input chunk must be a multiple of encode_align.

Note that this function only may panic in those cases. The function may also return the correct value in some cases depending on the implementation. In other words, those limits are the guarantee below which the function will not panic, and not the guarantee above which the function will panic.

fn encode_align(&self) -> usize

Returns the minimum alignment when chunking a long input

See encode_len for context.

fn encode_mut(&self, input: &[u8], output: &mut [u8])

Encodes input in output

Panics

Panics if the output length does not match the result of encode_len for the input length.

Examples

use data_encoding::BASE64;
# let mut buffer = vec![0; 100];
let input = b"Hello world";
let output = &mut buffer[0 .. BASE64.encode_len(input.len())];
BASE64.encode_mut(input, output);
assert_eq!(output, b"SGVsbG8gd29ybGQ=");

fn encode_mut_str<'a>(&self, input: &[u8], output: &'a mut [u8]) -> &'a str

Encodes input in output and returns it as a &str

It is guaranteed that output and the return value only differ by their type. They both point to the same range of memory (pointer and length).

Panics

Panics if the output length does not match the result of encode_len for the input length.

Examples

use data_encoding::BASE64;
# let mut buffer = vec![0; 100];
let input = b"Hello world";
let output = &mut buffer[0 .. BASE64.encode_len(input.len())];
assert_eq!(BASE64.encode_mut_str(input, output), "SGVsbG8gd29ybGQ=");

fn encode_append(&self, input: &[u8], output: &mut String)

Appends the encoding of input to output

Examples

use data_encoding::BASE64;
# let mut buffer = vec![0; 100];
let input = b"Hello world";
let mut output = "Result: ".to_string();
BASE64.encode_append(input, &mut output);
assert_eq!(output, "Result: SGVsbG8gd29ybGQ=");

fn new_encoder<'a>(&'a self, output: &'a mut String) -> Encoder<'a>

Returns an object to encode a fragmented input and append it to output

See the documentation of Encoder for more details and examples.

fn encode_write(&self, input: &[u8], output: &mut impl Write) -> Result

Writes the encoding of input to output

This allocates a buffer of 1024 bytes on the stack. If you want to control the buffer size and location, use [Encoding::encode_write_buffer()] instead.

Errors

Returns an error when writing to the output fails.

fn encode_write_buffer(&self, input: &[u8], output: &mut impl Write, buffer: &mut [u8]) -> Result

Writes the encoding of input to output using a temporary buffer

Panics

Panics if the buffer is shorter than 510 bytes.

Errors

Returns an error when writing to the output fails.

fn encode_display<'a>(&'a self, input: &'a [u8]) -> Display<'a>

Returns an object to display the encoding of input

Examples

use data_encoding::BASE64;
assert_eq!(
    format!("Payload: {}", BASE64.encode_display(b"Hello world")),
    "Payload: SGVsbG8gd29ybGQ=",
);

fn encode(&self, input: &[u8]) -> String

Returns encoded input

Examples

use data_encoding::BASE64;
assert_eq!(BASE64.encode(b"Hello world"), "SGVsbG8gd29ybGQ=");

fn decode_len(&self, len: usize) -> Result<usize, DecodeError>

Returns the maximum decoded length of an input of length len

See decode_mut for when to use it. In particular, the actual decoded length might be smaller if the actual input contains padding or ignored characters.

Panics

May panic if len is greater than usize::MAX / 8:

• len <= 536_870_911 when target_pointer_width = "32"
• len <= 2_305843_009213_693951 when target_pointer_width = "64"

If you need to decode an input of length greater than this limit (possibly of infinite length), then you must decode your input chunk by chunk with decode_mut, making sure that you take into account how many bytes have been read from the input and how many bytes have been written to the output:

• Ok(written) means all bytes have been read and written bytes have been written
• Err(DecodePartial { error, .. }) means an error occurred if error.kind != DecodeKind::Length or this was the last input chunk
• Err(DecodePartial { read, written, .. }) means that read bytes have been read and written bytes written (the error can be ignored)

Note that this function only may panic in those cases. The function may also return the correct value in some cases depending on the implementation. In other words, those limits are the guarantee below which the function will not panic, and not the guarantee above which the function will panic.

Errors

Returns an error if len is invalid. The error kind is Length and the position is the greatest valid input length.

fn decode_mut(&self, input: &[u8], output: &mut [u8]) -> Result<usize, DecodePartial>

Decodes input in output

Returns the length of the decoded output. This length may be smaller than the output length if the input contained padding or ignored characters. The output bytes after the returned length are not initialized and should not be read.

Panics

Panics if the output length does not match the result of decode_len for the input length. Also panics if decode_len fails for the input length.

Errors

Returns an error if input is invalid. See decode for more details. The are two differences though:

• Length may be returned only if the encoding allows ignored characters, because otherwise this is already checked by decode_len.
• The read first bytes of the input have been successfully decoded to the written first bytes of the output.

Examples

use data_encoding::BASE64;
# let mut buffer = vec![0; 100];
let input = b"SGVsbA==byB3b3JsZA==";
let output = &mut buffer[0 .. BASE64.decode_len(input.len()).unwrap()];
let len = BASE64.decode_mut(input, output).unwrap();
assert_eq!(&output[0 .. len], b"Hello world");

fn decode(&self, input: &[u8]) -> Result<Vec<u8>, DecodeError>

Returns decoded input

Errors

Returns an error if input is invalid. The error kind can be:

• Length if the input length is invalid. The position is the greatest valid input length.
• Symbol if the input contains an invalid character. The position is the first invalid character.
• Trailing if the input has non-zero trailing bits. This is only possible if the encoding checks trailing bits. The position is the first character containing non-zero trailing bits.
• Padding if the input has an invalid padding length. This is only possible if the encoding uses padding. The position is the first padding character of the first padding of invalid length.

Examples

use data_encoding::BASE64;
assert_eq!(BASE64.decode(b"SGVsbA==byB3b3JsZA==").unwrap(), b"Hello world");

fn bit_width(&self) -> usize

Returns the bit-width

fn interpret_byte(&self, byte: u8) -> Character

Interprets a byte as a character

fn is_canonical(&self) -> bool

Returns whether the encoding is canonical

An encoding is not canonical if one of the following conditions holds:

• trailing bits are not checked
• padding is used
• characters are ignored
• characters are translated

fn specification(&self) -> Specification

Returns the encoding specification