Basic Usage

Introduction

In this document is everything you need to know to get started with all the basic features of QuesoStruct. This was covered in the README, however it is worth mentioning again that QuesoStruct is primarily a code generator. Included with the code generation is a library package that contains commonly used data structures written for operation and interaction with other QuesoStruct code elements.

Marking code for generation

QuesoStruct's main feature of course is generating serialization code. As such, the most important part of your code to mark up are data fields in your classes. Taking the class example from the README we have:

using QuesoStruct;

[StructType]
public partial class MyStruct
{ 
    [StructMember]
    public uint Id { get; set; }
    
    [StructMember]
    public float X { get; set; }
    
    [StructMember]
    public float Y { get; set; }
    
    [StructMember]
    public float Z { get; set; }
}

It is essentially a 32-bit precision 3-vector with some attached metadata, the Id field.

There are a few important points to make about the expectations the code generator has.

Most importantly, you must declare your class as partial!!!

Next, regarding the declaration of your data fields:

1. There is a limited set of types that you may use. These include byte, sbyte, ushort, short, uint, int, ulong, long, float, and double. Because of the large variety of ways other types such as bool may be handled, it is not included as a primitive of QuesoStruct, as the other integer data types are often sufficient and can be processed using a boolean expression.

   Know that data fields may additionally be of any other type you create as long as you have marked it up for use with QuesoStruct.

2. The primitive types may only be written by their short aliases, i.e how they are written in #1. The long aliases such as UInt8, Int32, Single, Double, etc. will not be handled properly by QuesoStruct's generator (yet. defo is a TODO for v1.1)

3. Any data members annotated with [StructMember] MUST be public properties with both get and set implemented.

Using generated serialization code

After marking up your code, you will of course want to use the generated serialization code! The API used to access it is very simple. For the example MyStruct class above, one would write:

using DeltaStruct;
...
var serializer = Serializers.Get<MyStruct>();

But that's only the first part of it. Now you must create a Context instance over which the serializer will operate:

var context = new Context(stream /* some .NET Stream object, most likely a FileStream or MemoryStream */,
                          Endianess.Little /* or Endianess.Big. You may also use Context.SystemEndianess */, 
                          Encoding.ASCII /* only matters if you are using QuesoStruct.NullTerminatingString 
                                            but must be specified either way */);

Now you may use the Read and Write methods as you see fit:

var myStruct = serializer.Read(context);
/* ...or... */
serializer.Write(myStruct, context);

Learn more about QuesoStruct

Now that you've got the hang of basic serialization with QuesoStruct, see the Primitives, Pointers, or Collections pages next to learn more!