ktsu.DelegateTransform 1.1.22

ktsu.DelegateTransform

A utility library for transforming values using delegates in C#.

Introduction

DelegateTransform is a utility library that provides methods for transforming values using various delegate types in C#. It offers a clean and efficient way to apply transformations using ActionRef, Func, and FuncRef delegates, making your code more readable and functional.

Important: All With methods return a new transformed value - they never mutate the original input. This provides functional programming semantics even when using reference-based delegates.

Features

• ActionRef Transformations: Modify copies of values by reference using action delegates
• Func Transformations: Transform values using function delegates
• FuncRef Transformations: Transform values by reference using function delegates that return values
• Copy-on-Transform: Original values are never mutated
• Generic Implementation: Works with any value or reference type

Supported Frameworks

• .NET 10.0, 9.0, 8.0, 7.0, 6.0
• .NET Standard 2.1

Installation

Package Manager Console

Install-Package ktsu.DelegateTransform

.NET CLI

dotnet add package ktsu.DelegateTransform

Package Reference

<PackageReference Include="ktsu.DelegateTransform" Version="x.y.z" />

Usage Examples

With ActionRef

The With method can be used with an ActionRef<T> delegate to apply a transformation by reference and return the result:

using ktsu.DelegateTransform;

int input = 5;
int result = DelegateTransform.With(input, (ref int x) => x *= 2);
// result is 10, input is still 5 (original unchanged)

With Func

The With method can be used with a Func<T, T> delegate to transform the input value:

using ktsu.DelegateTransform;

int input = 5;
int result = DelegateTransform.With(input, x => x * 2);
// result is 10

With FuncRef

The With method can be used with a FuncRef<T> delegate to transform the input value by reference:

using ktsu.DelegateTransform;

int input = 5;
int result = DelegateTransform.With(input, (ref int x) => x * x);
// result is 25, input is still 5 (original unchanged)

Chaining Transformations

You can chain multiple transformations by nesting calls:

using ktsu.DelegateTransform;

// Starting value
string input = "example";

// Chain of transformations
string step1 = DelegateTransform.With(input, s => s.ToUpper());           // "EXAMPLE"
string step2 = DelegateTransform.With(step1, s => s.Replace("EX", "**")); // "**AMPLE"
string result = DelegateTransform.With(step2, s => s + " transformed");   // "**AMPLE transformed"

Console.WriteLine(result); // Outputs: **AMPLE transformed

Complex Object Transformations

using ktsu.DelegateTransform;

var person = new Person { Name = "John", Age = 30 };

// Transform using ActionRef (for reference types, the object is modified)
Person updatedPerson = DelegateTransform.With(person, (ref Person p) => {
    p.Name = p.Name.ToUpper();
    p.Age += 1;
});

Console.WriteLine($"{updatedPerson.Name}, {updatedPerson.Age}"); // Outputs: JOHN, 31

// Transform using Func to create a string description
string description = DelegateTransform.With(person, p =>
    $"{p.Name} is {p.Age} years old");

Console.WriteLine(description); // Outputs: JOHN is 31 years old

API Reference

Delegate Types

// Custom delegate for actions on references
public delegate void ActionRef<T>(ref T item);

// Custom delegate for functions on references
public delegate T FuncRef<T>(ref T item);

DelegateTransform Static Class

The main class providing transformation methods.

Methods

All methods throw ArgumentNullException if the delegate is null.

Design Principles

Copy-on-Transform

The library follows a functional programming pattern where the original input is never mutated:

public static T With<T>(T input, ActionRef<T> @delegate)
{
    Ensure.NotNull(@delegate);

    T output = input;  // Creates a copy
    @delegate(ref output);
    return output;
}

This ensures predictable behavior and prevents side effects on the original values.

Performance Considerations

For value types (structs), a copy is made before transformation. For large structs where you want to avoid copying, consider using the FuncRef<T> overload which passes by reference and returns the modified value.

For reference types (classes), the "copy" is actually a copy of the reference, so the underlying object can be modified. If you need true immutability for reference types, create a new instance within your delegate.

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

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