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 and Func 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
- 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 = input.With((ref int x) => x *= 2);
// result is 10, input is still 5 (original unchanged)
An expression-bodied lambda such as (ref int x) => x++ binds to this overload too, so 5.With((ref int x) => x++)
returns 6. To compute a new value instead of modifying one, use a Func<T, TResult>.
With Func
The With method can be used with a Func<T, TResult> delegate to transform the input value. The result can be the same type as the input or a different one:
using ktsu.DelegateTransform;
int input = 5;
int result = input.With(x => x * 2);
// result is 10
Chaining Transformations
Every With method is an extension method that returns the transformed value, so calls chain fluently:
using ktsu.DelegateTransform;
string result = "example"
.With(s => s.ToUpper()) // "EXAMPLE"
.With(s => s.Replace("EX", "**")) // "**AMPLE"
.With(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 = person.With((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 = person.With(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);
DelegateTransform Static Class
The static class holding the With extension methods. Call them on the value, as in input.With(...).
Naming the class, as in DelegateTransform.With(input, ...), does not compile from other ktsu.*
namespaces, where DelegateTransform resolves to the namespace of the same name.
Methods
| Method |
Parameters |
Return Type |
Description |
With<T> |
this T input, ActionRef<T> delegate |
T |
Creates a copy, applies the action by reference, returns the modified copy |
With<T, TResult> |
this T input, Func<T, TResult> delegate |
TResult |
Applies a function to the input and returns the result, which may be a different type |
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>(this 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), the ActionRef<T> overload copies the input once and lets the delegate modify that copy in place. The Func<T, TResult> overload passes the input by value, as any method parameter would.
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:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- 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.