netrexmc / binary-utils Goto Github PK

Binary Utils Macro Derive

BinaryUtils provides one derive macro BinaryIo.

This macro will implement both the Read and Write traits from interfaces. By default, this macro will read and write in the order the fields are declared in. In the future it may be possible to change this with an attribute, but this is not marked as a priority.

Require attribute

The require attribute allows you to require a previous field. This attribute requires the type to be that of the field must be Option<T<dyn Reader + dyn Writer>>.

Syntax:

#[require(<IDENT>)]

Example:

The following example requires field B to exist in order to try and decode C

pub struct ABC {
    a: u8,
    b: Option<u8>,
    #[require(B)]
    c: Option<u8>
}

Satisfy Attribute

This attribute provides functionality which allows you to optionally decode or encode a field or type. Conditionals are useful if you want to avoid using enums as wrapper types to support conditional logic.

Syntax:

#[satisfy(<EXPR>)]

Example:

The following is an example of a conditional attribute with the BinaryIo macro.

#[BinaryIo]
pub struct FramePacket {
    pub id: u16,
    // split_channel will only be read if the following condition
    // is specified
    #[satisfy(((self.id & 224) >> 5) == 3)]
    pub split_channel: Option<u8>,
}

Skip Attribute

This attribute does as the name implies; it skips the given field on both encoding and decoding. This field will not be used in encoding or decoding.

Syntax:

#[skip]

Example:

The following example skips field B and only encodes both A and C in the binary stream.

#[derive(BinaryIo)]
pub AC {
    A: u8,
    #[skip]
    B: u8,
    C: u8
}

pub fn test_ac() {
    let ac = AC { A: 1, B: 2, C: 3 };
    assert_eq!(ac.write_init().as_slice(), &[1, 3]);
}

Edit: Identifiers and expressions are now their literal types, not a string.

The following methods need to be fully implemented:

• read_signed_var_int
• read_var_long
• read_signed_var_long
• read_triad
• read_triad_le

The following methods need to be checked:

• read_int
• read_short
• read_signed_short
• read_int_le

There should either be an added type, or some other way to use encode/decode a slice of bytes with binary-utils.

If they should, what should they return?

Keep the API the same as a lot of Netrex depends on BinaryUtil now and a BC break is not necessarily ideal at the moment.

The idea for this rewrite would be to optimize the internals to include 0 clones as it's an unnecessary allocation each time we allocate a Stream when we could pass by reference.

Currently, we are decoding these as "shorts" which are 2, bytes. Ints are 4 bytes according to protocol.

If they should, what should they return?

Read triad has a byte size of 3, however no numeric type in rust has a byte size of 3, therefore when reading a triad currently, we are reading 4 bytes to satisfy the requirements of u32::try_into. This means that the method will return an triad as it reads another byte that should not be read.

The solution will need a helper function to perform a bit operation on all three bytes to convert them to a corresponding u32 to avoid using the try_into helper trait provided by the standard library.

An example case of this issue is: Bytes are u8 and read_byte should return a u8.
EG:

fn read_byte(&mut self) -> u16 { // ..
}

Should be:

fn read_byte(&mut self) -> u8 {
    let byte = self[self.offset];
    self.increase_offset(Some(1));
    byte
}

This is a necessary change because the functional names are misleading to what they actually do.

In the current rfc for 0.3.0 (#13) I mention the possibility to use this ability within enums and have them be derivable with BinaryIo.

This feature would make the following code block valid:

#[derive(BinaryIo)]
#[repr(u8)]
pub enum NamedEnum {
	One { foo: u8 }
}

fn test() {
	let a = NamedEnum::One { foo: 3 };
	a.write_to_bytes(); // [0, 3]
}

If you read any LE value one after another, for some reason you can an error Unwrap on None, which I think is a result of the try_into on the primitive type aka, the LE is passing a byte too short to compose on the native type.