Trait push_decode::Encoder

pub trait Encoder: Sized {
    // Required methods
    fn encoded_chunk(&self) -> &[u8] ;
    fn next(&mut self) -> bool;

    // Provided methods
    fn track_position(self) -> EncoderPositionTracker<Self> { ... }
    fn write_to_vec(self, buf: &mut Vec<u8>) { ... }
    fn write_all_sync<W: Write + BufWrite>(self, writer: W) -> Result<()> { ... }
    fn write_all_sync_lgio<W: BufWrite>(
        self,
        writer: W
    ) -> Result<(), W::WriteError> { ... }
    fn write_all_tokio<W: AsyncWrite + BufWrite>(
        self,
        writer: W
    ) -> TokioEncodeFuture<W, Self>  { ... }
    fn write_all_async_std<W: Write + BufWrite>(
        self,
        writer: W
    ) -> AsyncStdEncodeFuture<W, Self>  { ... }
    fn write_all_futures_0_3<W: AsyncWrite + BufWrite>(
        self,
        writer: W
    ) -> Futures0Dot3EncodeFuture<W, Self>  { ... }
    fn then<E: Encoder, F: FnMut() -> E>(
        self,
        second_encoder_constructor: F
    ) -> Then<Self, E, F> { ... }
    fn chain<T: Encoder>(self, second_encoder: T) -> Chain<Self, T> { ... }
}

Represents types producing bytes of some encoded value.

Required Methods

fn encoded_chunk(&self) -> &[u8]

Provides next chunk of encoded bytes.

The returned bytes represent a part of the value being encoded and should be written to a writer by the consumer. Empty returned value indicates end - there are no more bytes to be encoded.

The returned value MUST be the same for all calls of encoded_chunk until next() is called. IOW it’s not allowed to use interior mutability or global state (randomness) to affect the returned value.

It’s recommended that this method returns bytes within the value if possible or minimal required buffer otherwise. The consumers of the trait are responsible for buffering, so buffering inside encoder would decrease performance.

fn next(&mut self) -> bool

Advances the state to get the next chunk of encoded bytes.

Calling this method signals to the encoder that the current chunk was fully processed. The encoder MUST either:

• return true and provide the next chunk of data in folowing calls to encoded_chunk.
• return false indicating there is no more data.

The encoder MUST NOT panic or cause similar undesirable behavior if next was called again after it previously returned false. It must simply return false again.

Note that the implementor DOES NOT need to guarantee that encoded_chunk is empty after this method returned false and for performance reasons it’s not advisable to do in release builds. The consumers are responsible for handling this situation. The consumers may use track_position to get a more convenient interface handling these edge-cases and tracking byte position.

Provided Methods

fn track_position(self) -> EncoderPositionTracker<Self>

Returns a wrapper that tracks the position of processed bytes.

The returned wrapper has a bit different interface that is more suitable for writing into writers. It can handle partial writes and makes handling of end easier. Thus downstream consumers are encouraged to use it where it makes sense.

fn write_to_vec(self, buf: &mut Vec<u8>)

Available on crate feature alloc only.

Writes all encoded bytes to a vec.

Note that this does not call reserve since there’s no way to know the amount to reserve. This should be handled by the code producing the decoder instead.

fn write_all_sync<W: Write + BufWrite>(self, writer: W) -> Result<()>

Available on crate feature std only.

Writes all encoded bytes to the std writer.

fn write_all_sync_lgio<W: BufWrite>( self, writer: W ) -> Result<(), W::WriteError>

Available on crate feature lgio only.

Writes all encoded bytes to the std writer.

fn write_all_tokio<W: AsyncWrite + BufWrite>( self, writer: W ) -> TokioEncodeFuture<W, Self>

Available on crate feature tokio only.

Writes all encoded bytes to the tokio async writer.

The returned future resolves to std::io::Result<()>.

fn write_all_async_std<W: Write + BufWrite>( self, writer: W ) -> AsyncStdEncodeFuture<W, Self>

Available on crate feature async-std only.

Writes all encoded bytes to the async-std async writer.

The returned future resolves to std::io::Result<()>.

fn write_all_futures_0_3<W: AsyncWrite + BufWrite>( self, writer: W ) -> Futures0Dot3EncodeFuture<W, Self>

Available on crate feature futures_0_3 only.

Writes all encoded bytes to the futures 0.3 async writer.

The returned future resolves to std::io::Result<()>.

fn then<E: Encoder, F: FnMut() -> E>( self, second_encoder_constructor: F ) -> Then<Self, E, F>

Chains an encoder constructed by second_encoder_constructor after this one.

This is similar to chain but only incurs the cost of creating the encoder if it’s actually needed. So if encoding stops before finishing (e.g. due to error) no CPU time or memory is wasted.

This will also save memory if the second encoder is larger than F.

Note: F needs to be FnMut instead of FnOnce to correctly handle panics.

fn chain<T: Encoder>(self, second_encoder: T) -> Chain<Self, T>

Chains another encoder after this one.

This requires second encoder to be eagerly created which may waste CPU time if encoding stops early. You should consider using then instead, which may save memory as well.

Object Safety

This trait is not object safe.

Implementors

impl<A: Encoder, B: Encoder> Encoder for Chain<A, B>

impl<A: Encoder, B: Encoder, F: FnMut() -> B> Encoder for Then<A, B, F>

impl<T: AsRef<[u8]>> Encoder for BytesEncoder<T>

impl<T: Int> Encoder for IntEncoder<T>