What is an in parameter in C#

C# 7.2 adds the in keyword to complement the existing ref and out keywords when you write a method that passes arguments by reference. The in keyword specifies that you are passing the parameter by reference and the called method does not modify the value passed to it.

This addition provides a full vocabulary to express your design intent. Value types are copied when passed to a called method when you do not specify any of the following modifiers. Each of these modifiers specify that a value type is passed by reference, avoiding the copy. Each modifier expresses a different intent:

out: This method sets the value of the argument used as this parameter.
ref: This method may set the value of the argument used as this parameter.
in: This method does not modify the value of the argument used as this parameter.

When you add the in modifier to pass an argument by reference, you declare your design intent is to pass arguments by reference to avoid unnecessary copying. You do not intend to modify the object used as that argument. The following code shows an example of a method that calculates the distance between two points in 3D space.

private static double CalculateDistance(in Point3D point1, in Point3D point2)
{
double xDifference = point1.X – point2.X;
double yDifference = point1.Y – point2.Y;
double zDifference = point1.Z – point2.Z;

return Math.Sqrt(xDifference * xDifference + yDifference * yDifference + zDifference * zDifference);
}

The arguments are two structures that each contain three doubles. A double is 8 bytes, so each argument is 24 bytes. By specifying the in modifier, you pass 4-byte or 8-byte reference to those arguments, depending on the architecture of the machine. The difference in size is small, but it can quickly add up when your application calls this method in a tight loop using many different values.

The in modifier complements out and ref in other ways as well. You cannot create overloads of a method that differ only in the presence of in, out or ref. These new rules extend the same behavior that had always been defined for out and ref parameters.

The in modifier may be applied to any member that takes parameters: methods, delegates, lambdas, local functions, indexers, operators.

Unlike ref and out arguments, you may use literal values or constants for the argument to an inparameter. Also, unlike a ref or out parameter, you don’t need to apply the in modifier at the call site. The following code shows you two examples of calling the CalculateDistance method. The first uses two local variables passed by reference. The second includes a temporary variable created as part of the method call.

var distance = CalculateDistance(pt1, pt2);
var fromOrigin = CalculateDistance(pt1, new Point3D());

There are several ways in which the compiler ensures that the read-only nature of an inargument is enforced. First of all, the called method can’t directly assign to an in parameter. It can’t directly assign to any field of an in parameter. In addition, you cannot pass an inparameter to any method demanding the ref or out modifier. The compiler enforces that the inargument is a readonly variable. You can call any instance method that uses pass-by-value semantics. In those instances, a copy of the in parameter is created. Because the compiler can create a temporary variable for any in parameter, you can also specify default values for any in parameter. The follow code uses that to specify the origin (point 0,0) as the default value for the second point:

private static double CalculateDistance2(in Point3D point1, in Point3D point2 = default)
{
double xDifference = point1.X – point2.X;
double yDifference = point1.Y – point2.Y;
double zDifference = point1.Z – point2.Z;

return Math.Sqrt(xDifference * xDifference + yDifference * yDifference + zDifference * zDifference);
}

The in parameter designation can also be used with reference types or built in numeric values. However, the benefits in both cases are minimal, if any.