Enum savefile::Schema

#[repr(C, u32)]
pub enum Schema {
    Struct(SchemaStruct),
    Enum(SchemaEnum),
    Primitive(SchemaPrimitive),
    Vector(Box<Schema>, VecOrStringLayout),
    Array(SchemaArray),
    SchemaOption(Box<Schema>),
    Undefined,
    ZeroSize,
    Custom(String),
    Boxed(Box<Schema>),
    Slice(Box<Schema>),
    Str,
    Reference(Box<Schema>),
    Trait(bool, AbiTraitDefinition),
    FnClosure(bool, AbiTraitDefinition),
    Recursion(usize),
}

The schema represents the save file format of your data structure. It is a tree, consisting of various types of nodes in the savefile format. Custom Serialize-implementations cannot add new types to this tree, but must reuse these existing ones. See the various enum variants for more information.

Note, the Schema actually carries two different pieces of information

• The disk format
• The memory format. The latter is only used by SavefileAbi.

Note, schema instances may choose to not specify any memory format. If so, SavefileAbi will have to resort to serialization.

Exactly how the memory format is specified varies for the variants. Check the variant documentation.

Variants

Struct(SchemaStruct)

Represents a struct. Custom implementations of Serialize are encouraged to use this format.

Enum(SchemaEnum)

Represents an enum.

Primitive(SchemaPrimitive)

Represents a primitive: Any of the various integer types (u8, i8, u16, i16 etc…), or String

Vector(Box<Schema>, VecOrStringLayout)

A Vector of arbitrary nodes, all of the given type. This has a specified memory format unless the VecOrStringLayout value is ‘Unknown’.

Array(SchemaArray)

An array of N arbitrary nodes, all of the given type This has a specified memory format unless the VecOrStringLayout value is ‘Unknown’.

SchemaOption(Box<Schema>)

An Option variable instance of the given type. This has a specified memory format (a pointer to instance of ‘Schema’)

Undefined

Basically a dummy value, the Schema nodes themselves report this schema if queried. This never has a specified memory format.

ZeroSize

A zero-sized type. I.e, there is no data to serialize or deserialize. This always has a specified memory format.

Custom(String)

A user-defined, custom type. The string can be anything. The schema only matches if the string is identical. Use with caution. Consider if your type is aptly represented as a Struct or Enum instead. This never has a specified memory format.

Boxed(Box<Schema>)

The savefile format of a Box<T> is identical to that of T. But SavefileAbi still needs to represent Box<T> separate from T, since their memory layout isn’t the same.

Slice(Box<Schema>)

Savefile does not support deserializing unsized slices. But SavefileAbi supports these as parameters. Savefile schema still needs to be able to represent them.

Str

Savefile does not support deserializing &str, nor the unsized str. But SavefileAbi supports &str as parameters. It does not support str. Savefile schema still needs to be able to represent Str.

Reference(Box<Schema>)

Savefile does not support deserializing references. If it would, the savefile format of &T would be identical to that of T. But SavefileAbi still needs to represent &T separate from T, since their memory layout isn’t the same.

Trait(bool, AbiTraitDefinition)

Traits cannot be serialized, but they can be exchanged using savefile-abi Their memory layout is considered to depend on all method signatures, and the layouts of all argument types and all return types.

FnClosure(bool, AbiTraitDefinition)

This is just a trait. But it exists as a separate schema variant, since SavefileAbi automatically generates wrappers for standard Fn*-types, and these should not be mixed up with regular trait definitions, even if they would be identical Traits cannot be serialized, but they can be exchanged using savefile-abi Their memory layout is considered to depend on all method signatures, and the layouts of all argument types and all return types.

Recursion(usize)

The datastructure is recursive, and the datatype now continues from the element that is ‘depth’ layers higher in the schema tree. Note, the ‘depth’ only counts possible recursion points, i.e, objects such as ‘Box’, ‘Vec’ etc. This works, since the schema will only ever match if it is identical in memory and file, and because of this, counting only the recursion points is non-ambiguous.

Implementations

impl Schema

pub fn top_level_description(&self) -> String

Get a short description of the major type of this schema. ‘struct’, ‘enum’ etc.

pub fn layout_compatible(&self, b_native: &Schema) -> bool

Determine if the two fields are laid out identically in memory, in their parent objects.

pub fn new_tuple1<T1: WithSchema>( version: u32, context: &mut WithSchemaContext ) -> Schema

Create a 1-element tuple

pub fn new_tuple2<T1: WithSchema, T2: WithSchema>( version: u32, context: &mut WithSchemaContext ) -> Schema

Create a 2-element tuple

pub fn new_tuple3<T1: WithSchema, T2: WithSchema, T3: WithSchema>( version: u32, context: &mut WithSchemaContext ) -> Schema

Create a 3-element tuple

pub fn new_tuple4<T1: WithSchema, T2: WithSchema, T3: WithSchema, T4: WithSchema>( version: u32, context: &mut WithSchemaContext ) -> Schema

Create a 4-element tuple

pub fn serialized_size(&self) -> Option<usize>

Size

Trait Implementations

impl Clone for Schema

fn clone(&self) -> Schema

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Schema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deserialize for Schema

fn deserialize( deserializer: &mut Deserializer<'_, impl Read> ) -> Result<Self, SavefileError>

Deserialize and return an instance of Self from the given deserializer.

impl Introspect for Schema

Introspect is not implemented for Schema, though it could be

fn introspect_value(&self) -> String

Returns the value of the object, excluding children, as a string. Exactly what the value returned here is depends on the type. For some types, like a plain array, there isn’t much of a value, the entire information of object resides in the children. For other cases, like a department in an organisation, it might make sense to have the value be the name, and have all the other properties as children.

fn introspect_child<'a>( &'a self, _index: usize ) -> Option<Box<dyn IntrospectItem<'a> + 'a>>

Returns an the name and &dyn Introspect for the child with the given index, or if no child with that index exists, None. All the children should be indexed consecutively starting at 0 with no gaps, all though there isn’t really anything stopping the user of the trait to have any arbitrary index strategy, consecutive numbering 0, 1, 2, … etc is strongly encouraged.

fn introspect_len(&self) -> usize

Returns the total number of children. The default implementation calculates this by simply calling introspect_child with higher and higher indexes until it returns None. It gives up if the count reaches 10000. If your type can be bigger and you want to be able to introspect it, override this method.

impl Packed for Schema

unsafe fn repr_c_optimization_safe(_version: u32) -> IsPacked

This method returns true if the optimization is allowed for the protocol version given as an argument. This may return true if and only if the given protocol version has a serialized format identical to the memory layout of the given protocol version. Note, the only memory layout existing is that of the most recent version, so Packed-optimization only works when disk-format is identical to memory version.

impl PartialEq for Schema

fn eq(&self, other: &Schema) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Schema

fn serialize( &self, serializer: &mut Serializer<'_, impl Write> ) -> Result<(), SavefileError>

Serialize self into the given serializer. In versions prior to 0.15, ‘Serializer’ did not accept a type parameter. It now requires a type parameter with the type of writer expected.

impl WithSchema for Schema

fn schema(_version: u32, _context: &mut WithSchemaContext) -> Schema

Returns a representation of the schema used by this Serialize implementation for the given version. The WithSchemaContext can be used to guard against recursive data structures. See documentation of WithSchemaContext.

impl StructuralPartialEq for Schema