Table of Contents

Class CStructLayoutAttribute

Namespace
CStructSharp
Assembly
CStructSharp.dll

Asks the CStructSharp source generator to turn a layout into C# at compile time: one class per struct and union, an enum per layout enum, and straight-line Parse, Serialize, Update, and ResolveAddress methods on the attributed static partial class, with the same results and the same diagnostics as CStruct produces for the same definition and options.

[AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
public sealed class CStructLayoutAttribute : Attribute
Inheritance
CStructLayoutAttribute
Inherited Members

Remarks

The layout is the constructor argument or, with File, a .cstruct file the project lists as an AdditionalFiles item. The other properties mirror the CStruct constructor and CStructCompilationOptions. An option this attribute does not name takes the project's default from the matching CStructSharp* build property (CStructSharpSurface for Surface, and so on), then the library's.

Constructors

CStructLayoutAttribute()

Generates from the file named by File.

public CStructLayoutAttribute()

CStructLayoutAttribute(string)

Generates from layout text.

public CStructLayoutAttribute(string definition)

Parameters

definition string

The Portable v1 layout source.

Properties

Aligned

Gets or sets whether the portable composite-alignment rules apply.

public bool Aligned { get; set; }

Property Value

bool

BitfieldAllocation

Gets or sets which end of a storage unit bitfields are allocated from.

public BitfieldAllocation BitfieldAllocation { get; set; }

Property Value

BitfieldAllocation

BitfieldPacking

Gets or sets how bitfields pack into storage units.

public BitfieldPacking BitfieldPacking { get; set; }

Property Value

BitfieldPacking

CLongWidth

Gets or sets the width of C long in bits; 0 means the library default (64).

public int CLongWidth { get; set; }

Property Value

int

Codecs

Gets or sets the custom codecs the layout uses, one declaration per codec: "name" for a variable-length codec, "name:size" for a fixed size in bytes, "name:size:alignment" to also give the alignment ("name:*:alignment" for a variable-length one). The generator places fields with these facts; the class supplies the matching ICustomCodec instances, in the same order, from its static partial IReadOnlyList<ICustomCodec> CreateCodecs() method.

public string[]? Codecs { get; set; }

Property Value

string[]

ConstraintFailures

Gets or sets the exception type the generated readers throw for a field that breaks an @expect or @supports constraint. The default, Constraint, throws CStructConstraintException; FormatExceptions throws InvalidDataException (@expect) or NotSupportedException (@supports) with the constraint failure as the inner exception. The project default is the build property CStructSharpConstraintFailures.

public ConstraintFailureMode ConstraintFailures { get; set; }

Property Value

ConstraintFailureMode

DefaultEnumStorage

Gets or sets the storage type of an enum declared without one (enum kind { ... }); null means the library default.

public string? DefaultEnumStorage { get; set; }

Property Value

string

Defined

Gets or sets the preprocessor symbols defined for the layout.

public string[]? Defined { get; set; }

Property Value

string[]

Definition

Gets the layout text, when it was given inline.

public string? Definition { get; }

Property Value

string

Enumerators

Gets or sets whether each view of a fixed-size struct gets a foreach enumerator over consecutive records.

public bool Enumerators { get; set; }

Property Value

bool

Remarks

The full surface always has the enumerator. The Reader, Parser and Views surfaces leave it out unless this is true, because it adds code to every fixed-size struct. It needs Views.

File

Gets or sets the path of a .cstruct additional file, relative to the project, holding the layout text.

public string? File { get; set; }

Property Value

string

KeepNames

Gets or sets whether generated names keep the layout's spelling instead of becoming PascalCase.

public bool KeepNames { get; set; }

Property Value

bool

LittleEndian

Gets or sets whether neutral values are little-endian.

public bool LittleEndian { get; set; }

Property Value

bool

MaxValueBytes

Gets or sets the largest struct, in bytes, that a value-type shape (Struct, or Auto where it applies) may generate; a bigger struct is copied into every return value and variable, so the default of 1,024 keeps it a class (a large value also lives on the stack, which a deeply nested caller can overflow). The value must be between 1 and 65,536; Struct with another value is reported as CSG014, and Auto keeps the class. The project default is the build property CStructSharpMaxValueBytes.

public int MaxValueBytes { get; set; }

Property Value

int

PointerSize

Gets or sets the pointer width in bytes (1, 2, 4, or 8).

public int PointerSize { get; set; }

Property Value

int

Root

Gets or sets the declaration the plain Parse/Serialize methods use; the default is the first struct.

public string? Root { get; set; }

Property Value

string

RuntimeByteOrder

Gets or sets whether the byte order of neutral values (those spelled without a < or > suffix) is chosen when a value is read instead of when the layout is compiled.

public bool RuntimeByteOrder { get; set; }

Property Value

bool

Remarks

One layout then reads both byte orders: every Parse and TryParse takes a bool littleEndian after the source, a view's constructor and Enumerate take it after the source too, and LittleEndian is not used. It replaces a pair of layouts that differ only in LittleEndian. A field with an explicit suffix keeps its order.

It needs a surface that only reads (Reader, Parser or Views), and a layout whose bitfields sit in the same place in both byte orders; anything else is reported as CSG013.

Shape

Gets or sets whether each struct and union of the layout becomes a class (the default), a value type, a value type only where the layout qualifies, or just the value of a one-member layout; see GeneratedShape.

public GeneratedShape Shape { get; set; }

Property Value

GeneratedShape

Surface

Gets or sets how much code is generated; the default, Full, generates everything.

public GeneratedSurface Surface { get; set; }

Property Value

GeneratedSurface

Views

Gets or sets whether a zero-allocation ref struct view is generated per composite.

public bool Views { get; set; }

Property Value

bool

Remarks

It must stay true with Views, whose only output is the views.

Edit this page