Ref Readonly Parameters in C# with Examples

In this article, I will discuss Ref Read-Only Parameters in C# with Examples. Please read our previous article discussing Default Parameters in Lambda Expressions in C# with Examples. In C# 12, the language introduced the ref read-only parameter, which is a combination of ref and readonly. This feature enables passing parameters by reference while ensuring that the parameter cannot be modified inside the method. This performance enhancement avoids copying large structs or complex objects while preserving immutability within the method.

What’s New in C# 12 Related to ref readonly Parameters?

Before C# 12, we could use the ref keyword to pass parameters by reference, allowing them to be modified inside the method. However, there was no way to pass a parameter by reference while enforcing immutability inside the method.

In C# 12, we can now use ref readonly parameters, which allow you to pass parameters by reference while ensuring they are read-only inside the method. This adds a layer of safety and performance optimization for structs or objects that are expensive to copy.

What is a ref readonly Parameter?

A ref read-only parameter allows you to pass an argument by reference but with read-only semantics. This means the parameter can be accessed directly without creating a copy, but it cannot be modified within the method. The following is the syntax for using ref read-only in C# 12.

public void MyMethod(ref readonly MyStruct param)
{
    // param cannot be modified inside this method.
}

Example: Using ref readonly in C# 12

Let’s look at an example of a large struct representing a Point with x, y, and z coordinates. We pass this struct to a method using ref readonly to avoid copying the data, and we ensure the struct’s values cannot be modified inside the method.

namespace CSharp12NewFeatures
{
    // Define a large struct
    public struct Point
    {
        public int X;
        public int Y;
        public int Z;

        public Point(int x, int y, int z)
        {
            X = x;
            Y = y;
            Z = z;
        }

        public void Display()
        {
            Console.WriteLine($"Point: ({X}, {Y}, {Z})");
        }
    }

    public class Program
    {
        static void Main()
        {
            // Initialize a large struct
            Point point = new Point(1, 2, 3);

            // Pass the struct by reference with readonly semantics
            ModifyPoint(ref point);

            // Point remains unmodified
            point.Display();  // Output: Point: (1, 2, 3)
        }

        // Method that takes ref readonly parameter
        static void ModifyPoint(ref readonly Point p)
        {
            // Cannot modify p.X, p.Y, or p.Z
            // p.X = 10;  // Compile-time error: Cannot modify a readonly parameter

            // Accessing the values, but not modifying them
            Console.WriteLine($"Inside ModifyPoint: ({p.X}, {p.Y}, {p.Z})");
        }
    }
}

Code Explanation:

Point Struct: This Point struct represents a large data structure with X, Y, and Z coordinates.
ref readonly Parameter: The method ModifyPoint takes the Point struct by reference (ref readonly). This ensures, the struct is not copied and the struct cannot be modified inside the method.
Displaying the Point: In the Main method, we call ModifyPoint, and after the method returns, we display the Point object. It remains unchanged because ref readonly ensures immutability within the method.

Output:

Key Features of ref readonly Parameters in C# 12:

Pass By Reference: The ref keyword allows the parameter to be passed by reference, meaning that changes made to the parameter inside the method will affect the original argument outside the method.
Read-Only Inside Method: The readonly modifier ensures that the parameter cannot be modified inside the method. This helps prevent accidental modifications while still benefiting from the performance gains of passing by reference.
Performance: Passing large structs by reference (ref readonly) can be significantly more efficient than passing by value, especially when dealing with large structs, arrays, or other memory-intensive types.
Immutability: The readonly part ensures that the object passed by reference remains immutable within the method. This provides guarantees about not altering the object’s state, which is particularly useful in multi-threaded environments.

Real-Time Example: Geospatial Calculation System with ref readonly Parameters

In this example, we will simulate a geospatial system that handles 3D points (representing coordinates in a 3D space), calculates distances between points, and applies transformations (like scaling and translation) to the points. The ref read-only parameter ensures we pass large structs (representing 3D points) efficiently by reference while keeping them immutable within the method.

namespace CSharp12NewFeatures
{
    // A struct representing a 3D point (e.g., geographic coordinate or game world position)
    public struct Point3D
    {
        public double X;
        public double Y;
        public double Z;

        public Point3D(double x, double y, double z)
        {
            X = x;
            Y = y;
            Z = z;
        }

        // Method to display the coordinates of the point
        public void DisplayCoordinates()
        {
            Console.WriteLine($"Point3D: X = {X}, Y = {Y}, Z = {Z}");
        }
    }

    public class Program
    {
        static void Main()
        {
            // Define two 3D points
            var pointA = new Point3D(3, 4, 5);
            var pointB = new Point3D(6, 8, 10);

            // Calculate distance between two points using ref readonly
            double distance = CalculateDistance(ref pointA, ref pointB);
            Console.WriteLine($"Distance between Point A and Point B: {distance}");

            // Apply transformations: scaling and translation
            TransformPoint(ref pointA, 2);  // Scale Point A by a factor of 2
            pointA.DisplayCoordinates();   // Display transformed Point A

            // Apply translation to Point B
            TranslatePoint(ref pointB, 5, 5, 5);
            pointB.DisplayCoordinates();   // Display translated Point B
        }

        // Method to calculate the distance between two points (using ref readonly)
        static double CalculateDistance(ref readonly Point3D pointA, ref readonly Point3D pointB)
        {
            // Using the Pythagorean theorem to calculate the Euclidean distance
            double deltaX = pointB.X - pointA.X;
            double deltaY = pointB.Y - pointA.Y;
            double deltaZ = pointB.Z - pointA.Z;

            return Math.Sqrt(deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ);
        }

        // Method to apply a scaling transformation (scale the point)
        static void TransformPoint(ref Point3D point, double scale)
        {
            // Scale each coordinate by the provided factor
            point.X *= scale;
            point.Y *= scale;
            point.Z *= scale;
        }

        // Method to apply a translation transformation (move the point)
        static void TranslatePoint(ref Point3D point, double dx, double dy, double dz)
        {
            // Translate the point by the given offsets
            point.X += dx;
            point.Y += dy;
            point.Z += dz;
        }
    }
}

Explanation of the Code:

Point3D Struct: This struct represents a 3D point with X, Y, and Z coordinates. It has a constructor to initialize these values and a method to display the coordinates.
ref readonly Parameters: In the CalculateDistance method, we pass pointA and pointB using ref readonly. This ensures that the Point3D struct is passed by reference (for efficiency) but cannot be modified inside the method. The ref readonly ensures that the coordinates of pointA and pointB remain immutable in the CalculateDistance method.
TransformPoint and TranslatePoint Methods: These methods take ref parameters because they are modifying the point’s values (i.e., scaling and translating the coordinates). Since ref readonly doesn’t allow modifications, the TransformPoint and TranslatePoint methods pass the Point3D struct by ref, but are allowed to change the coordinates.
Operations: The CalculateDistance method calculates the Euclidean distance between two points using the Pythagorean theorem: distance = sqrt((x2 – x1)^2 + (y2 – y1)^2 + (z2 – z1)^2). The TransformPoint method scales the point’s coordinates by a given factor. The TranslatePoint method moves the point by the specified offsets in each dimension (X, Y, and Z).

Output:

Limitations and Restrictions of ref readonly Parameters:

Cannot Modify the Parameter Inside the Method: The main limitation of ref readonly is that while you are passing the parameter by reference for performance reasons, you cannot modify its value inside the method.
Does Not Allow Assignment: You cannot assign a new value to the ref readonly parameter inside the method because it is meant to be immutable within the method.

Example to Understand Limitations and Restrictions:

In this example, we will create a Vector3D struct, representing a 3D vector, and perform two operations:

Magnitude Calculation (calculating the length of the vector).
Dot Product (calculating the dot product with another vector).

We will demonstrate the limitations of ref readonly parameters by showing what happens when you attempt to modify the struct, or assign a new value to it inside the method. The following example code is self-explained, so please read the comment lines for a better understanding.

namespace CSharp12NewFeatures
{
    // Define a struct representing a 3D vector
    public struct Vector3D
    {
        public double X;
        public double Y;
        public double Z;

        public Vector3D(double x, double y, double z)
        {
            X = x;
            Y = y;
            Z = z;
        }

        // Method to calculate the magnitude (length) of the vector
        public double Magnitude()
        {
            return Math.Sqrt(X * X + Y * Y + Z * Z);
        }
    }

    public class Program
    {
        static void Main()
        {
            // Initialize two vectors
            var vector1 = new Vector3D(3, 4, 5);
            var vector2 = new Vector3D(1, 2, 3);

            // Attempting to pass the vector by ref readonly
            Console.WriteLine("Magnitude of Vector1: " + CalculateMagnitude(ref vector1));
            Console.WriteLine("Dot Product of Vector1 and Vector2: " + CalculateDotProduct(ref vector1, ref vector2));

             // Uncommenting the following lines will result in compile-time errors due to ref readonly limitations
             ModifyVector(ref vector1);   // Error: Cannot modify ref readonly parameter
             AssignNewValue(ref vector1); // Error: Cannot assign new value to ref readonly parameter
        }

        // Method to calculate the magnitude of a vector (using ref readonly)
        static double CalculateMagnitude(ref readonly Vector3D vector)
        {
            // Cannot modify the vector here, as it's passed ref readonly
            // vector.X = 10;  // Compile-time error: Cannot modify ref readonly parameter

            // Return the magnitude (length) of the vector
            return vector.Magnitude();
        }

        // Method to calculate the dot product between two vectors (using ref readonly)
        static double CalculateDotProduct(ref readonly Vector3D vector1, ref readonly Vector3D vector2)
        {
            // Cannot modify the vectors here either
            // vector1.X = 10;  // Compile-time error: Cannot modify ref readonly parameter
            // vector2.Y = 20;  // Compile-time error: Cannot modify ref readonly parameter

            // Calculate and return the dot product
            return vector1.X * vector2.X + vector1.Y * vector2.Y + vector1.Z * vector2.Z;
        }

        // Example of an invalid operation: Attempting to modify a ref readonly parameter
        static void ModifyVector(ref readonly Vector3D vector)
        {
            // This will result in a compile-time error because the vector is passed as ref readonly.
            vector.X = 100;  // Error: Cannot modify ref readonly parameter
        }

        // Example of an invalid operation: Attempting to assign a new value to a ref readonly parameter
        static void AssignNewValue(ref readonly Vector3D vector)
        {
            vector = new Vector3D(10, 10, 10);  // Error: Cannot assign new value to ref readonly parameter
        }
    }
}

Code Explanation:

Vector3D Struct: The Vector3D struct represents a 3D vector with X, Y, and Z coordinates. The Magnitude method calculates the length of the vector using the Pythagorean theorem.
ref readonly Parameters: The CalculateMagnitude and CalculateDotProduct methods both take parameters ref readonly, meaning the vectors are passed by reference but cannot be modified inside the method. You can access the vector values (e.g., vector.X), but you cannot modify the X, Y, or Z values inside these methods due to the readonly restriction.
Invalid Operations: The ModifyVector and AssignNewValue methods demonstrate the limitations of ref readonly. Attempting to modify the parameter (vector.X = 10) will result in a compile-time error because the parameter is passed with readonly semantics. You cannot assign a new value to a ref readonly parameter (vector = new Vector3D(10, 10, 10)) because it is immutable within the method.

When to Use ref readonly Parameters?

The ref readonly parameter is especially useful in the following scenarios:

Large Structs: When you have large structs (such as struct types that contain arrays or other large data), passing them by value can incur a significant performance cost. Using ref readonly allows you to avoid copying the data while ensuring it is not modified inside the method.
Immutable Data: If you need to pass large objects or structs by reference but don’t want to risk accidentally changing the data inside the method, ref readonly ensures the object remains immutable.
Optimizing Performance: It provides performance benefits over passing parameters by value while ensuring the safety of not modifying the data within the method.

The introduction of ref readonly parameters in C# 12 provides a powerful way to pass large structs by reference without copying them, while also ensuring immutability within the method. This combination of performance and safety is especially useful when working with large data structures and needing to ensure that data is not modified unintentionally. It allows for high-performance applications while preserving clean and maintainable code.

In the next article, I will discuss Alias Any Type in C# with Examples. In this article, I explain Ref Readonly Parameters in C# with Examples. I want your feedback. Please post your feedback, questions, or comments about this article.

Dot Net Tutorials

About the Author: Pranaya Rout

Pranaya Rout has published more than 3,000 articles in his 11-year career. Pranaya Rout has very good experience with Microsoft Technologies, Including C#, VB, ASP.NET MVC, ASP.NET Web API, EF, EF Core, ADO.NET, LINQ, SQL Server, MYSQL, Oracle, ASP.NET Core, Cloud Computing, Microservices, Design Patterns and still learning new technologies.