Class DataModel

Namespace

LlamaLogic.Packages.Models.Data

Assembly

LlamaLogic.Packages.dll

Represents a SimData or CombinedTuning resource (🔓)

public sealed class DataModel : Model, IModel<DataModel>, IModel

Inheritance

object

Model

DataModel

Implements

IModel<DataModel>

IModel

Inherited Members

Model.GetName(ResourceType, Stream)

Model.GetNameAsync(ResourceType, Stream, CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Synchronous API Only

Due to performance considerations, this object model provides no asynchronous API. Thus, the caller will be blocked until the entire SimData or CombinedTuning resource is decoded by Decode(ReadOnlyMemory<byte>) or encoded by Encode(). Front-end developers are advised to wrap calls to either method with Run(Func<Task>) to avoid blocking the UI thread. The asynchronous API of DataBasePackedFile will do this automatically.

Eager Loading

When a SimData or CombinedTuning resource is passed to Decode(ReadOnlyMemory<byte>), the entire resource is decoded to compose a complete graph of all tables in the resource, including their metadata and records. For some CombinedTuning resources shipped by Maxis, this may result in a large number of tables and records being loaded into memory and take a significant amount of time.

Thread Safety

For performance reasons, this class and its supporting classes in this namespace are not thread-safe. If a caller has need for parallelized use of a DataModel, they are expected to manage synchronization on their own.

Exposed Reference Structure

To grant callers maximum control, the structure of references from the SimData or CombinedTuning resource is preserved and unabstracted.

While the classes which implement DataModelReference have properties to produce useful compositions (e.g. the Value property of DataModelString will convert the null-terminated sequence of ASCII characters it references in a DataModelTable of CHAR8 values to a string), these conveniences are processed on-demand and only so long as the reference has remained valid. The original data being referenced remains stored by instances of DataModelTable as it appeared in the resource at the time it was decoded. All instances of DataModelReference monitor the row (or rows) of the DataModelTable they are referencing and will invalidate themselves if any constituent element is altered by the caller.

Encode() reacts to invalid references by writing the RELOFFSET_NULL value in their place. Callers can check to see if something they've done has invalidated a reference by checking its IsValid property.

Properties

this[int]

Gets the table at the specified index

public DataModelTable this[int index] { get; }

Parameters

index int

Property Value

DataModelTable

this[string]

Gets the table with the specified name

public DataModelTable this[string name] { get; }

Parameters

name string

Property Value

DataModelTable

ResourceName

Gets the name of this resource if it has one

public override string? ResourceName { get; }

Property Value

string

SupportedTypes

Gets a list of resource types that this model supports

public static ISet<ResourceType> SupportedTypes { get; }

Property Value

ISet<ResourceType>

Tables

Gets the tables in this resource

public Collection<DataModelTable> Tables { get; }

Property Value

Collection<DataModelTable>

Version

Gets/sets the DataModelVersion of this resource

public DataModelVersion Version { get; set; }

Property Value

DataModelVersion

Methods

Decode(ReadOnlyMemory<byte>)

Decodes the resource in raw format to produce an operable model (🔄️🏃)

public static DataModel Decode(ReadOnlyMemory<byte> data)

Parameters

data ReadOnlyMemory<byte>

Returns

DataModel

Exceptions

UnexpectedFormatDecodingException

The data appears to be a CombinedTuning resource in XML format

Encode()

Encodes the resource model into raw format (🔄️🏃)

public override ReadOnlyMemory<byte> Encode()

Returns

ReadOnlyMemory<byte>

GetName(Stream)

Gets the name of a resource from its raw data, if it has one (🔄️💤)

public static string? GetName(Stream stream)

Parameters

stream Stream

Returns

string

GetNameAsync(Stream, CancellationToken)

Gets the name of a resource from its raw data, if it has one, asynchronously (🔄️💤)

public static Task<string?> GetNameAsync(Stream stream, CancellationToken cancellationToken = default)

Parameters

stream Stream

cancellationToken CancellationToken

Returns

Task<string>

GetTable(string)

Gets the table with the specified name

public DataModelTable GetTable(string name)

Parameters

name string

Returns

DataModelTable