ufotofu 0.12.0

Abstractions for lazily consuming and producing sequences
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

use crate::{codec::DecodeError, prelude::*};

/// A trait for types which can be decoded relative to a `RelativeTo` from a sequence of `Symbol`s.
///
/// More precisely, this trait may be implemented by types that belong to an [relative encoding relation](super). The trait specifies (via the [`RelativeDecodable::relative_decode`] method) how to decode values relative to other values by reading a sequence of symbols from a [`BulkProducer`].
///
/// API contracts:
///
/// - For any fixed `rel: RelativeTo`, [`relative_decode`](RelativeDecodable::relative_decode) must fulfil the same API contracts as [`decode`](crate::codec::Decodable::decode) does for [`Decodable`](crate::codec::Decodable).
/// - For types that also implement [`RelativeEncodable`](super::RelativeEncodable), if `val` is the result of successfully decoding relative to some value `rel`, then `val.can_be_encoded_relative_to(rel)` must be true.
///
/// <br/>Counterpart: the [`RelativeEncodable`](super::RelativeEncodable) trait.
pub trait RelativeDecodable<RelativeTo, Symbol = u8>: Sized {
    /// Reason why decoding can fail (beyond an unexpected end of input or a producer error).
    type ErrorReason;

    /// Decodes the symbols produced by the given bulk producer relative to `rel` into a `Self`, or yields an error if the producer does not produce a valid relative encoding.
    ///
    /// <br/>Counterpart: the [`RelativeEncodable::relative_encode`](super::RelativeEncodable::relative_encode) method.
    async fn relative_decode<P>(
        rel: &RelativeTo,
        producer: &mut P,
    ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>
    where
        P: BulkProducer<Item = Symbol> + ?Sized,
        Self: Sized;
}

/// Decoding for a [relative encoding relation](super) with a one-to-one mapping between values and their codes (i.e., for any one value relative to which to encode, the relation is a [bijection](https://en.wikipedia.org/wiki/Bijection)).
///
/// Implementations of this trait may specialise arbitrary relative encoding relations to a canonic subset.
///
/// API contracts:
///
/// - For any fixed `rel: RelativeTo`, [`relative_decode_canonic`](RelativeDecodableCanonic::relative_decode_canonic) must fulfil the same API contracts as [`decode_canonic`](crate::codec::DecodableCanonic::decode_canonic) does for [`DecodableCanonic`](crate::codec::DecodableCanonic).
///
/// There is no corresponding `RelativeEncodableCanonic` trait, because [`RelativeEncodable`](super::RelativeEncodable) already fulfils the dual requirement of two nonequal values yielding nonequal codes when encoded relative to the same value.
pub trait RelativeDecodableCanonic<RelativeTo, Symbol = u8>:
    RelativeDecodable<RelativeTo, Symbol>
{
    /// The type for reporting that the sequence of symbols to decode was not a valid canonic encoding of any value of type `Self`.
    ///
    /// Typically contains at least as much information as [`Self::ErrorReason`](RelativeDecodable::ErrorReason). If the relative encoding relation implemented by [`RelativeDecodable`] is already canonic, then [`ErrorCanonic`](RelativeDecodableCanonic::ErrorCanonic) should be equal to [`Self::ErrorReason`](RelativeDecodable::ErrorReason).
    type ErrorCanonic: From<Self::ErrorReason>;

    /// Decodes the symbols produced by the given bulk producer relative to `rel` into a `Self`, and errors if the input encoding is not the canonical one.
    async fn relative_decode_canonic<P>(
        rel: &RelativeTo,
        producer: &mut P,
    ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorCanonic>>
    where
        P: BulkProducer<Item = Symbol> + ?Sized,
        Self: Sized;
}