Struct data_encoding::Padded
[−]
[src]
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
[src]
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>
&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>
&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
[src]
impl Copy for Padded
[src]
impl Clone for Padded
[src]
fn clone(&self) -> Padded
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl PartialEq for Padded
[src]
fn eq(&self, __arg_0: &Padded) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, __arg_0: &Padded) -> bool
This method tests for !=
.