akanse.EfficientUnionGenerator 0.1.0

EfficientUnionGenerator

<img src="https://img.shields.io/badge/-GitHub-blue.svg?logo=github" />

Based on C# 15's Union type support, EfficientUnionGenerator provides highly efficient Union type support that avoids boxing.

• The unions which are generated by EfficientUnionGenerator can contain both of unmanaged types and managed types.
• Managed types are erasured its type information into object field and they are casted by type checking when read.
• Unmanaged types are convolved into single field and they are identified by an enum identifier.
• For unmanaged types, also the type identifier can be convolved into the value field. In this case, specified bit mask is used to set or read type identifier.

How to use

EfficientUnionGenerator regards structs which are annotated with EfficientUnion.EfficientUnionAttribute as union types and generates union type support for them. Also it regards public partial constructors with single parameter as the members of the union.

Following code is the most simple example of how to use EfficientUnionGenerator.

using EfficientUnion;

[EfficientUnion]
public readonly partial struct Int32OrString
{
    public partial Int32OrString(int x);
    public partial Int32OrString(string x);
}

If all of the members of the union are unmanaged types, the union type gets also unmanaged type.

using EfficientUnion;

// This struct is also unmanaged type because all of its members are unmanaged types.
[EfficientUnion]
public readonly partial struct SignedInteger
{
    public partial SignedInteger(sbyte x);
    public partial SignedInteger(short x);
    public partial SignedInteger(int x);
    public partial SignedInteger(long x);
}

You can specify the bit mask for type identifier by unmanagedFieldMask property of EfficientUnionAttribute.

using System.Runtime.CompilerServices;
using EfficientUnion;

// If it handles only positive value, the 31-th bit can be used as type identifier.
// This optimization can embed the type identifier in the value field, and eliminate the need to allocate a separate identifier field.
[EfficientUnion(unmanagedFieldMask: 0x80_00_00_00u)]
public readonly partial struct PositiveOnlyIntOrFloat
{
    public partial PositiveOnlyIntOrFloat(int value);
    public partial PositiveOnlyIntOrFloat(float value);
}

public static class Program
{
    public static void Main()
    {
        Console.WriteLine(Unsafe.SizeOf<PositiveOnlyIntOrFloat>());  // output: 4
    }
}

You can specify the type identifier value by using EfficientUnion.EnumBitPatternAttribute. This is useful for such case of struct unions identified by version number field.

using EfficientUnion;

// ELF header is identified into 32-bit ELF header or 64-bit ELF header by the value of e_ident[4].
// NOTE: remind that unmanagedFieldMask is little endianness.
[EfficientUnion(Mode, unmanagedFieldMask: 0x00_00_00_FF_00_00_00_00uL)]
public readonly partial struct ElfHeader
{
    private const TypeIdentifierValueMode Mode =
        TypeIdentifierValueMode.ExplicitAssign
        | TypeIdentifierValueMode.LeaveWhenCreate
        | TypeIdentifierValueMode.LeaveWhenGet;

    [EnumBitPattern(0x00_00_00_01_00_00_00_00uL)] public partial ElfHeader(Elf32Header x);
    [EnumBitPattern(0x00_00_00_02_00_00_00_00uL)] public partial ElfHeader(Elf64Header x);
}