Trait EncodeExt

pub trait EncodeExt: Encode + Sized {
    // Provided methods
    fn with_item(item: Self::Item) -> Result<Self>
       where Self: Default { ... }
    fn map_err<E, F>(self, f: F) -> MapErr<Self, E, F>
       where F: Fn(Error) -> E,
             Error: From<E> { ... }
    fn map_from<T, F>(self, f: F) -> MapFrom<Self, T, F>
       where F: Fn(T) -> Self::Item { ... }
    fn try_map_from<T, E, F>(self, f: F) -> TryMapFrom<Self, T, E, F>
       where F: Fn(T) -> Result<Self::Item, E>,
             Error: From<E> { ... }
    fn optional(self) -> Optional<Self> { ... }
    fn max_bytes(self, n: u64) -> MaxBytes<Self> { ... }
    fn length(self, n: u64) -> Length<Self> { ... }
    fn chain<T: Encode>(self, other: T) -> TupleEncoder<(Self, T)> { ... }
    fn repeat<I>(self) -> Repeat<Self, I>
       where I: Iterator<Item = Self::Item> { ... }
    fn pre_encode(self) -> PreEncode<Self> { ... }
    fn slice(self) -> Slice<Self> { ... }
    fn last(self, item: Self::Item) -> Last<Self> { ... }
    fn encode_into_bytes(&mut self, item: Self::Item) -> Result<Vec<u8>> { ... }
}

An extension of Encode trait.

Provided Methods

fn with_item(item: Self::Item) -> Result<Self>

where Self: Default,

Creates a new encoder instance that has the given initial item.

Examples

use bytecodec::{Encode, EncodeExt};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = U8Encoder::with_item(7).unwrap();
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, [7]);
assert!(encoder.is_idle());

fn map_err<E, F>(self, f: F) -> MapErr<Self, E, F>

where F: Fn(Error) -> E, Error: From<E>,

Creates an encoder for modifying encoding errors produced by self.

Examples

The following code shows the idiomatic way to track encoding errors:

use bytecodec::{Encode, EncodeExt, Eos};
use bytecodec::fixnum::U8Encoder;
use trackable::track;

let encoder = U8Encoder::with_item(7).unwrap();
let mut encoder = encoder.map_err(|e| track!(e, "oops!")); // or track_err!(encoder, "oops!")
let error = track!(encoder.encode(&mut [][..], Eos::new(true))).err().unwrap();

assert_eq!(error.to_string(), "\
UnexpectedEos (cause; assertion failed: `!eos.is_reached()`; \
               buf.len()=0, size=0, self.offset=0, b.as_ref().len()=1)
HISTORY:
  [0] at src/bytes.rs:53
  [1] at src/fixnum.rs:116
  [2] at src/encode.rs:9 -- oops!
  [3] at src/encode.rs:10\n");

fn map_from<T, F>(self, f: F) -> MapFrom<Self, T, F>

where F: Fn(T) -> Self::Item,

Creates an encoder that converts items into ones that suited to the self encoder by calling the given function.

Examples

use bytecodec::{Encode, EncodeExt};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = U8Encoder::new().map_from(|s: String| s.len() as u8);
let item = "Hello World!".to_owned();
encoder.start_encoding(item).unwrap();
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, [12]);

fn try_map_from<T, E, F>(self, f: F) -> TryMapFrom<Self, T, E, F>

where F: Fn(T) -> Result<Self::Item, E>, Error: From<E>,

Creates an encoder that tries to convert items into ones that suited to the self encoder by calling the given function.

Examples

use bytecodec::{Encode, EncodeExt, ErrorKind, Result};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;
use trackable::{track, track_assert, track_panic};

let mut output = Vec::new();
let mut encoder = U8Encoder::new().try_map_from(|s: String| -> Result<_> {
    track_assert!(s.len() <= 0xFF, ErrorKind::InvalidInput);
    Ok(s.len() as u8)
});
let item = "Hello World!".to_owned();
encoder.start_encoding(item).unwrap();
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, [12]);

fn optional(self) -> Optional<Self>

Creates an encoder that represents an optional encoder.

It takes Option<Self::Item> items. If Some(_) is passed as an argument for start_encoding method, it will be encoded as ordinally. On the other hand, if None is passed, it will be ignored completely.

Examples

use bytecodec::{Encode, EncodeExt};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = U8Encoder::new().optional();

encoder.start_encoding(None).unwrap();
encoder.encode_all(&mut output).unwrap();

encoder.start_encoding(Some(9)).unwrap();
encoder.encode_all(&mut output).unwrap();

assert_eq!(output, [9]);

fn max_bytes(self, n: u64) -> MaxBytes<Self>

Creates an encoder that will fail if the number of encoded bytes of an item exceeds n.

Examples

use bytecodec::{Encode, EncodeExt, ErrorKind};
use bytecodec::bytes::Utf8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = Utf8Encoder::new().max_bytes(3);

encoder.start_encoding("foo").unwrap(); // OK
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, b"foo");

encoder.start_encoding("hello").unwrap(); // Error
let error = encoder.encode_all(&mut output).err().unwrap();
assert_eq!(*error.kind(), ErrorKind::InvalidInput);

fn length(self, n: u64) -> Length<Self>

Creates an encoder that required to encode each item exactly at the specified number of bytes.

Examples

use bytecodec::{Encode, EncodeExt, ErrorKind};
use bytecodec::bytes::Utf8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = Utf8Encoder::new().length(3);
encoder.start_encoding("hey").unwrap(); // OK
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, b"hey");

let mut encoder = Utf8Encoder::new().length(3);
encoder.start_encoding("hello").unwrap(); // Error (too long)
let error = encoder.encode_all(&mut output).err().unwrap();
assert_eq!(*error.kind(), ErrorKind::UnexpectedEos);

let mut encoder = Utf8Encoder::new().length(3);
encoder.start_encoding("hi").unwrap(); // Error (too short)
let error = encoder.encode_all(&mut output).err().unwrap();
assert_eq!(*error.kind(), ErrorKind::InvalidInput);

fn chain<T: Encode>(self, other: T) -> TupleEncoder<(Self, T)>

Takes two encoders and creates a new encoder that encodes both items in sequence.

This is equivalent to call TupleEncoder::new((self, other)).

fn repeat<I>(self) -> Repeat<Self, I>

where I: Iterator<Item = Self::Item>,

Creates an encoder that repeats encoding of Self::Item.

Examples

use bytecodec::{Encode, EncodeExt, ErrorKind};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder = U8Encoder::new().repeat();
encoder.start_encoding(0..4).unwrap();
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, [0, 1, 2, 3]);

fn pre_encode(self) -> PreEncode<Self>

Creates an encoder that pre-encodes items when start_encoding method is called.

Although the number of memory copies increases, pre-encoding will enable to acquire the exact size of encoded items.

Examples

use bytecodec::{Encode, EncodeExt, ExactBytesEncode};
use bytecodec::fixnum::U8Encoder;
use bytecodec::io::IoEncodeExt;

let mut output = Vec::new();
let mut encoder =
    U8Encoder::new()
        .repeat()
        .pre_encode()
        .with_prefix(U8Encoder::new(), |body| body.exact_requiring_bytes() as u8);

encoder.start_encoding(0..3).unwrap();
encoder.encode_all(&mut output).unwrap();
assert_eq!(output, [3, 0, 1, 2]);

fn slice(self) -> Slice<Self>

Creates an encoder that makes it possible to slice the encoded byte sequence in arbitrary units.

Slicing encoded byte sequences makes it easier to multiplex them into a single sequence.

Examples

use bytecodec::{Encode, EncodeExt, Eos};
use bytecodec::bytes::Utf8Encoder;

let mut encoder = Utf8Encoder::new().slice();
encoder.start_encoding("foobarbaz").unwrap();

let eos = Eos::new(true);
let mut output = [0; 9];
let mut offset = 0;

encoder.set_consumable_bytes(3);
offset += encoder.encode(&mut output[offset..], eos).unwrap();
assert_eq!(offset, 3);
assert_eq!(encoder.is_idle(), false);
assert_eq!(encoder.consumable_bytes(), 0);

offset += encoder.encode(&mut output[offset..], eos).unwrap();
assert_eq!(offset, 3);

encoder.set_consumable_bytes(6);
offset += encoder.encode(&mut output[offset..], eos).unwrap();
assert_eq!(offset, 9);
assert_eq!(encoder.is_idle(), true);
assert_eq!(output.as_ref(), b"foobarbaz");

fn last(self, item: Self::Item) -> Last<Self>

Creates an encoder that cannot accept any more items except the given one.

fn encode_into_bytes(&mut self, item: Self::Item) -> Result<Vec<u8>>

Encodes the given item and returns the resulting bytes.

Examples

use bytecodec::EncodeExt;
use bytecodec::fixnum::U16beEncoder;

let mut encoder = U16beEncoder::new();
assert_eq!(encoder.encode_into_bytes(0x1234).unwrap(), [0x12, 0x34]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T: Encode> EncodeExt for T