diff --git a/README.md b/README.md index 575d770..31b4c55 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,40 @@ > beta version -Multiplatform binary tools collection, including portable serialization of the compact and fast [Bipack] format, that works well also in the browser and in native targets. +Multiplatform binary tools collection, including portable serialization of the compact and fast [Bipack] format, that +works well also in the browser and in native targets. # Usage +Add our maven: + +```kotlin +repositories { + // ... + maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven") +} +``` + +And add dependecy to the proper place in yuor project like this: + +``` +dependencies { + // ... + implementation("net.sergeych:mp_bintools:0.0.2-SNAPSHOT") +} +``` +Use your desired version. TODO: specify maven: how? # Bipack ## Why? -Bipack is a compact and efficiten binary serialization library (and format) was designed with the following main goals: +Bipack is a compact and efficient binary serialization library (and format) was designed with the following main goals: + +### Allow easy unpacking existing binary structures + +Yuo describe your structure as `@Serializable` classes, and - voila, bipack decodes and encodes it for you! ### - be as compact as possible @@ -57,7 +80,8 @@ deserialization, using `@CrcProtected`. This allows to check the data consistenc # Usage -Use kotlinx serializatino as usual. There are following Bipack-specific annotation at your service. All class annotations could be combined. +Use kotlinx serializatino as usual. There are following Bipack-specific annotation at your service. All class +annotations could be combined. ## @Extendable @@ -84,23 +108,27 @@ Bipack will properly deserialize the data serialzied for an old version. ## @CrcProtected -Bipack will calculate and store CRC32 of serialized data at the end, and automatically check it on deserializing throwing `InvalidFrameCRCException` if it does not match. +Bipack will calculate and store CRC32 of serialized data at the end, and automatically check it on deserializing +throwing `InvalidFrameCRCException` if it does not match. It adds 4 bytes to the serialized data. ## @Framed -Put the CRC32 of the serializing class name (`@SerialName` allows to change it as usual) and checks it on deserializing. Throws `InvalidFrameHeaderException` if it does not match. +Put the CRC32 of the serializing class name (`@SerialName` allows to change it as usual) and checks it on deserializing. +Throws `InvalidFrameHeaderException` if it does not match. It adds 4 bytes to the serialized data. ## @Unisgned -This __field annontation__ allows to store __integer fields__ of any size more compact by not saving the sign. Could be applyed to both signed and unsigned integers of any size. +This __field annontation__ allows to store __integer fields__ of any size more compact by not saving the sign. Could be +applyed to both signed and unsigned integers of any size. ## @FixedSize(size) -Use it with fixed-size collections (like hashes, keys, etc.) to not keep collection size in the packed binary. It saves at least one byte. +Use it with fixed-size collections (like hashes, keys, etc.) to not keep collection size in the packed binary. It saves +at least one byte. ## @Fixed @@ -110,14 +138,16 @@ Can be used with any integer type to store/restor it as is, fixed-size, big-endi - Int, UInt: 4 bytes - Long, ULong: 8 bytes -Note that without this modifier all integers are serialized into variable-length compressed format, see class [Smartint] from this library. +Note that without this modifier all integers are serialized into variable-length compressed format, see class [Smartint] +from this library. Example: + ~~~kotlin @Serializable class Foo( - @Fixed - val eightBytesLongInt: Long + @Fixed + val eightBytesLongInt: Long ) // so: