Home

Awesome

Dusharp

NuGet

Dusharp is a C# source generator library for creating discriminated unions. This library allows you to define union types with ease, using attributes and partial methods. It is inspired by functional languages but built for C# developers.

Features

Installation

Dusharp is available as a NuGet package. You can install it using the NuGet package manager:

dotnet add package Dusharp

Usage

Dusharp uses attributes to generate discriminated unions and case methods. Here's how to get started:

1. Define a Union

To define a union, annotate a class with the [Dusharp.UnionAttribute] attribute.

using Dusharp;

[Union]
public partial class Shape<T>
    where T : struct, INumber<T>
{
}

2. Define Union Cases

Define union cases by creating public static partial methods and marking them with the [Dusharp.UnionCaseAttribute] attribute. The method body will be automatically generated.

using Dusharp;

[Union]
public partial class Shape<T>
    where T : struct, INumber<T>
{
    [UnionCase]
    public static partial Shape<T> Circle(T radius);

    [UnionCase]
    public static partial Shape<T> Rectangle(T width, T height);
}

3. Match on Union

You can easily perform pattern matching on a union using the Match method. The source generator will create the Match method based on the defined union cases.

Shape<double> shape = Shape<double>.Circle(5.0);

string result = shape.Match(
    radius => $"Circle with radius {radius}",
    (width, height) => $"Rectangle with width {width} and height {height}");

Console.WriteLine(result); // Output: Circle with radius 5.0

4. Compare Unions

Union cases can be compared for equality using the auto-generated equality methods. This allows for checking if two unions are the same.

Shape<double> shape1 = Shape<double>.Circle(5.0);
Shape<double> shape2 = Shape<double>.Circle(5.0);

Console.WriteLine(shape1.Equals(shape2)); // True
Console.WriteLine(shape1 == shape2); // True

Struct unions

Dusharp supports struct unions, allowing you to reduce allocations. You can define struct union the same way as for class union using the [Dusharp.UnionAttribute] attribute. This feature generates memory efficient unions.

Blittable Types

Blittable types (e.g., int, double, etc., and structs contain only blittable types) from different cases will share the same memory space using the [StructLayout(LayoutKind.Explicit)] attribute. This enables efficient memory usage by overlapping the fields in the union.

Reference Types

For reference type parameters, Dusharp uses a shared object fields to store reference type parameters from different cases. The object fields will be cast to their target types using the no-op Unsafe.As method, providing an efficient way to handle reference types in struct unions.

Example

For instance, consider a union that contains both blittable and reference type parameters:

[Union]
public partial struct TestUnion
{
    [UnionCase]
    public static partial TestUnion Case1(long value1, long value2);

    [UnionCase]
    public static partial TestUnion Case2(Guid value1, Guid value2);

    [UnionCase]
    public static partial TestUnion Case3(string value, Exception value2);

    [UnionCase]
    public static partial TestUnion Case4(Action value);
}

Generated Code Explanation

The source generator produces efficient code for this union by optimizing how blittable and reference types are stored and managed in memory. Here's the structure of the generated code:

partial struct TestUnion : System.IEquatable<TestUnion>
{
    private object Field0;
    private object Field1;
    private TestUnionBlittableData UnionBlittableDataField;
    private byte Index;
}

Memory Layout Optimization for Blittable Types

For blittable types, the generator uses a memory-efficient layout where the fields of different union cases are overlapped in memory using the [StructLayout(LayoutKind.Explicit)] attribute. This reduces memory usage by sharing memory space for compatible types.

[StructLayout(LayoutKind.Explicit)]
internal struct TestUnionBlittableData
{
    [FieldOffset(0)]
    public Case1BlittableData Case1Data;

    [FieldOffset(0)]
    public Case2BlittableData Case2Data;

    [StructLayout(LayoutKind.Auto)]
    public struct Case1BlittableData
    {
        public long value1;
        public long value2;
    }

    [StructLayout(LayoutKind.Auto)]
    public struct Case2BlittableData
    {
        public System.Guid value1;
        public System.Guid value2;
    }
}

Size of a union

In this example, the size of the TestUnion union is 56 bytes:

Thus, the total size is 16 + 32 + 8 = 56 bytes.

Important Note

All of these details about memory layout and struct size are implementation-specific and subject to change. Users should not rely on these internal details or use them directly in their code. The behavior and memory management may evolve in future versions to improve performance or efficiency.

Upcoming Features

License

This project is licensed under the MIT License - see the LICENSE file for details.