Trait Writer 

pub trait Writer {
    type Ok;
    type Mut<'this>: Writer
       where Self: 'this;

    // Required methods
    fn finish<C>(&mut self, cx: C) -> Result<Self::Ok, C::Error>
       where C: Context;
    fn borrow_mut(&mut self) -> Self::Mut<'_>;
    fn extend<C>(
        &mut self,
        cx: C,
        buffer: Vec<u8, C::Allocator>,
    ) -> Result<(), C::Error>
       where C: Context;
    fn write_bytes<C>(&mut self, cx: C, bytes: &[u8]) -> Result<(), C::Error>
       where C: Context;

    // Provided method
    fn write_byte<C>(&mut self, cx: C, b: u8) -> Result<(), C::Error>
       where C: Context { ... }
}

The trait governing how a writer works.

Examples

use musli::{Context, Writer};
use musli::context;

// Example using Writer as a trait bound
fn write_greeting<W, C>(mut writer: W, cx: C) -> Result<W::Ok, C::Error>
where
    W: Writer,
    C: Context,
{
    writer.write_bytes(cx, b"Hello")?;
    writer.write_byte(cx, b' ')?;
    writer.write_bytes(cx, b"World")?;
    writer.finish(cx)
}

let mut writer = Vec::new();
let cx = context::new();

write_greeting(&mut writer, &cx)?;
assert_eq!(writer, b"Hello World");

Required Associated Types

type Ok

The value returned from writing the value.

type Mut<'this>: Writer where Self: 'this

Reborrowed type.

Why oh why would we want to do this over having a simple &'this mut T?

We want to avoid recursive types, which will blow up the compiler. And the above is a typical example of when that can go wrong. This ensures that each call to borrow_mut dereferences the Reader at each step to avoid constructing a large muted type, like &mut &mut &mut VecWriter.

Required Methods

fn finish<C>(&mut self, cx: C) -> Result<Self::Ok, C::Error>

where C: Context,

Finalize the writer and return the output.

fn borrow_mut(&mut self) -> Self::Mut<'_>

Reborrow the current type.

Examples

use musli::{Context, Writer};
use musli::context;

let mut writer = Vec::new();
let cx = context::new();

{
    let mut borrowed = writer.borrow_mut();
    borrowed.write_bytes(&cx, b"Hello")?;
}

writer.write_bytes(&cx, b" World")?;
writer.finish(&cx)?;
assert_eq!(writer, b"Hello World");

fn extend<C>( &mut self, cx: C, buffer: Vec<u8, C::Allocator>, ) -> Result<(), C::Error>

where C: Context,

Write a buffer to the current writer.

This method is used internally to write a musli Vec buffer to the writer. Most users will use write_bytes instead.

fn write_bytes<C>(&mut self, cx: C, bytes: &[u8]) -> Result<(), C::Error>

where C: Context,

Write bytes to the current writer.

Examples

use musli::{Context, Writer};
use musli::context;

let mut writer = Vec::new();
let cx = context::new();

writer.write_bytes(&cx, b"Hello")?;
writer.write_bytes(&cx, b" ")?;
writer.write_bytes(&cx, b"World")?;
writer.finish(&cx)?;
assert_eq!(writer, b"Hello World");

Provided Methods

fn write_byte<C>(&mut self, cx: C, b: u8) -> Result<(), C::Error>

where C: Context,

Write a single byte.

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.

Implementations on Foreign Types

impl Writer for Vec<u8>

Available on crate feature alloc only.

type Ok = ()

type Mut<'this> = &'this mut Vec<u8> where Self: 'this

fn finish<C>(&mut self, _: C) -> Result<Self::Ok, C::Error>

where C: Context,

fn borrow_mut(&mut self) -> Self::Mut<'_>

fn extend<C>( &mut self, cx: C, buffer: Vec<u8, C::Allocator>, ) -> Result<(), C::Error>

where C: Context,

fn write_bytes<C>(&mut self, cx: C, bytes: &[u8]) -> Result<(), C::Error>

where C: Context,

fn write_byte<C>(&mut self, cx: C, b: u8) -> Result<(), C::Error>

where C: Context,

impl<W> Writer for &mut W

where W: ?Sized + Writer,

type Ok = <W as Writer>::Ok

type Mut<'this> = &'this mut W where Self: 'this

fn finish<C>(&mut self, cx: C) -> Result<Self::Ok, C::Error>

where C: Context,

fn borrow_mut(&mut self) -> Self::Mut<'_>

fn extend<C>( &mut self, cx: C, buffer: Vec<u8, C::Allocator>, ) -> Result<(), C::Error>

where C: Context,

fn write_bytes<C>(&mut self, cx: C, bytes: &[u8]) -> Result<(), C::Error>

where C: Context,

fn write_byte<C>(&mut self, cx: C, b: u8) -> Result<(), C::Error>

where C: Context,

Implementors

impl<'a> Writer for SliceMutWriter<'a>

type Ok = usize

type Mut<'this> = &'this mut SliceMutWriter<'a> where Self: 'this

impl<A> Writer for BufWriter<A>

where A: Allocator,

type Ok = ()

type Mut<'this> = &'this mut BufWriter<A> where Self: 'this

impl<W> Writer for Wrap<W>

where W: Write,

Available on crate feature std only.

type Ok = ()

type Mut<'this> = &'this mut Wrap<W> where Self: 'this

impl<const N: usize> Writer for FixedBytes<N>

type Ok = ()

type Mut<'this> = &'this mut FixedBytes<N> where Self: 'this