Relative encodings

[sgwilym]

New relative encoding traits

Adds RelativeEncodable and RelativeDecodable traits. But wait! Why the new traits, you ask? Why not just define a Relativity struct and implement Encoder and Decoder on those?

• Decoder::decode is a static method which takes a Ufotofu producer as its single parameter. But we need the reference value to to decode relative to! Thus we must have a RelativeDecoder trait which has the reference in question as a (&self) parameter.
• While it is possible to implement Encodable on a Relativity struct (see the first commit), symmetry between Encodable and Decodable traits has now been broken, which I found a bit confusing
• There is another kind of error exclusive to relative encodings which we'd like to be able to surface, which is IllegalRelativity. Some relative encodings require the subject being encoded to be logically included by the reference item, e.g. an Entry encoded relative to an Area must be included by that Area. With a Relativity struct, the only way to check for this would be to define custom constructors for each kind of relative pairing, which was possible to accidentally forget to do. But with a dedicated RelativeEncoder trait, we can return Result<(), RelativeEncodeError>.

All this considered it made more sense to me to have dedicated traits.

Fuzzing utilities

• relative_encoding_roundtrip (encode, decode, check it came out okay)
• relative_encoding_random (decode random bytes, encode, assert new encoding is exactly the same as the previous one)
• relative_encoding_random_less_strict(decode random bytes, encode, decode it again, assert the decoded object is the same the second time around)

Encodings

• Path relative to path
• Entry relative entry
• Entry relative area
• Entry relative range
• Area relative area
• 3dRange relative 3dRange

[AljoschaMeyer]

Decoder::decode is a static method which takes a Ufotofu producer as its single parameter. But we need the reference value to to decode relative to! Thus we must have a RelativeDecoder trait which has the reference in question as a (&self) parameter.

Good point. Yeah, I like the two separate traits, then.

There is another kind of error exclusive to relative encodings which we'd like to be able to surface, which is IllegalRelativity.

Not sure about this one. I think this should be a panic rather than an error, since it indicates a bug in your own implementation rather than an expected case that is allowed to happen.

[sgwilym]

Not sure about this one. I think this should be a panic rather than an error, since it indicates a bug in your own implementation rather than an expected case that is allowed to happen.

Agreed. RelativeEncodeError has been removed.