netrexmc / binary-utils Goto Github PK
View Code? Open in Web Editor NEWA panic free binary network utility library.
License: Apache License 2.0
A panic free binary network utility library.
License: Apache License 2.0
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.
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>
}
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>,
}
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.