Struct data_encoding::Padded

pub struct Padded { /* fields omitted */ }

Padded base-conversion encoding

The padded encoding extends the base-conversion encoding. This is only useful for octal, base32, and base64. And for those bases, it is only useful if the length of the data to encode is not known in advance.

Theory

Bases for which the bit-width N does not divide 8 may not concatenate encoded data. This comes from the fact that it is not possible to make the difference between trailing bits and encoding bits. Padding solves this issue by adding a new character (which is not a symbol) to discriminate between trailing bits and encoding bits. The idea is to work by blocks of lcm(8, N) bits, where lcm(8, N) is the least common multiple of 8 and N. When such block is not complete, it is padded.

Practice

For octal and base64, lcm(8, 3) == lcm(8, 6) == 24 bits or 3 bytes. For base32, lcm(8, 5) is 40 bits or 5 bytes. Let's consider octal and base64:

use data_encoding::{BASE64, Builder};
let octal = Builder::new(b"01234567").pad(b'=').padded().unwrap();
// We start encoding but we only have "B" for now.
assert_eq!(BASE64.encode(b"B"), "Qg==");
assert_eq!(octal.encode(b"B"), "204=====");
// Now we have "it".
assert_eq!(BASE64.encode(b"it"), "aXQ=");
assert_eq!(octal.encode(b"it"), "322720==");
// By concatenating everything, we may decode the original data.
assert_eq!(BASE64.decode_concat(b"Qg==aXQ=").unwrap(), b"Bit");
assert_eq!(octal.decode_concat(b"204=====322720==").unwrap(), b"Bit");

We have the following diagrams:

[base64] |   Q(16)   :   g(32)   :     =     :     =     |
[ octal] |  2  :  0  :  4  :  =  :  =  :  =  :  =  :  =  |
         |0 1 0 0 0 0 1 0|. . . . . . . .|. . . . . . . .|
[ ascii] |       B       |        end of block aligned --^
         ^-- beginning of block aligned

[base64] |   a(26)   :   X(23)   :   Q(16)   :     =     |
[ octal] |  3  :  2  :  2  :  7  :  2  :  0  :  =  :  =  |
         |0 1 1 0 1 0 0 1|0 1 1 1 0 1 0 0|. . . . . . . .|
[ ascii] |       i       |       t       |

Methods

impl Padded

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.

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

Encodes input in output.

Panics

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

Examples

use data_encoding::BASE64;
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(&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 decoded length of an input of length len

See decode_mut for when to use it.

Errors

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

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

Decodes input in output

Returns the length of the decoded output. This length may be smaller than output's length if the input is padded. The output bytes after the returned length are not initialized and should not be read.

Panics

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

Errors

Returns an error if input is invalid. The error kind can be Symbol, Trailing, or Padding.

Examples

use data_encoding::BASE64;
let input = b"SGVsbG8gd29ybGQ=";
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, Symbol, Trailing, or Padding.

Examples

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

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

Decodes concatenated input in output

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

Panics

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

Errors

Returns an error if input is invalid. The error kind can be Symbol, Trailing, or Padding.

Examples

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

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

Returns decoded concatenated input

Errors

Returns an error if input is invalid. The error kind can be Length, Symbol, Trailing, or Padding.

Examples

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

fn no_pad(&self) -> &NoPad

Returns the associated base-conversion encoding

Examples

use data_encoding::BASE64;
assert_eq!(BASE64.encode(b"Helo"), "SGVsbw==");
assert_eq!(BASE64.no_pad().encode(b"Helo"), "SGVsbw");

fn padding(&self) -> u8

Returns the padding character

Trait Implementations

impl Debug for Padded

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Copy for Padded

impl Clone for Padded

fn clone(&self) -> Padded

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq for Padded

fn eq(&self, __arg_0: &Padded) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Padded) -> bool

This method tests for !=.

impl Eq for Padded