The other answers on this page are complete and useful, but I wanted to add an additional point, which is that out
parameters, which your function is required to fully initialize, count as "safe to return" for the purposes of ref return.
Interestingly, combining this fact with another new C# 7 feature, inline declaration of 'out' variables, allows for the simulation of a general-purpose inline declaration of local variables capability:
helper function:
public static class _myglobals
{
/// <summary> Helper function for declaring local variables inline. </summary>
public static ref T local<T>(out T t)
{
t = default(T);
return ref t;
}
};
With this helper, the caller specifies the initialization of the "inline local variable" by assigning to the ref-return of the helper.
To demonstrate the helper, next is an example of a simple two-level comparison function which would be typical for an (e.g.) MyObj.IComparable<MyObj>.Compare
implementation. Although very simple, this type of expression can't get around needing a single local variable--without duplicating work, that is. Now normally, needing a local would block using an expression-bodied member which is what we'd like to do here, but the problem is easily solved with the above helper:
public int CompareTo(MyObj x) =>
(local(out int d) = offs - x.offs) == 0 ? size - x.size : d;
Walkthrough: Local variable d
is "inline-declared," and initialized with the result of computing the first-level compare, based on the offs fields. If this result is inconclusive, we fall back to returning a second level sort (based on the size fields). But in the alternative, we do still have the first-level result available to return, since it was saved in local d
.
Note that the above can also be done without the helper function, via C# 7 pattern matching:
public int CompareTo(MyObj other) =>
(offs - x.offs) is int d && d == 0 ? size - x.size : d;
include at the top of your source files:
using System;
using /* etc... */
using System.Xml;
using Microsoft.Win32;
using static _myglobals; // <-- puts function 'local(...)' into global name scope
namespace MyNamespace
{
// ...
The following examples show declaring a local variable inline with its initialization in C# 7. If initialization is not provided, it obtains default(T)
, as assigned by the local<T>(out T t)
helper function. This is only now possible with the ref return
feature, since ref return
methods are the only methods can be used as an ℓ-value.
example 1:
var s = "abc" + (local(out int i) = 2) + "xyz"; // <-- inline declaration of local 'i'
i++;
Console.WriteLine(s + i); // --> abc2xyz3
example 2:
if ((local(out OpenFileDialog dlg) = new OpenFileDialog // <--- inline local 'dlg'
{
InitialDirectory = Environment.CurrentDirectory,
Title = "Pick a file",
}).ShowDialog() == true)
{
MessageBox.Show(dlg.FileName);
}
The first example trivially assigns from an integer literal. In the second example, the inline local dlg
is assigned from a constructor (new
expression), and then the entire assignment expression is used for its resolved value to call an instance method (ShowDialog
) on the newly created instance. For precise clarity as a standalone example, it finishes by showing that the referred instance of dlg
did indeed need to be named as a variable, in order to fetch one of its properties.
[edit:] Regarding...
2. Ref locals are initialized to a certain storage location, and cannot be mutated to point to another.
...it would certainly be nice to have a ref
variable with a mutable referent, since this would help avoid expensive indexing bounds checks within loop bodies. Of course, that's also precisely why it's not allowed. You probably can't get around this (i.e. ref
to an array access expression with indexing containing ref
won't work; it gets permanently resolved to the element at the referenced position when initialized) but if it helps, note that you can take a ref
to a pointer, and this includes ref local:
int i = 5, j = 6;
int* pi = &i;
ref int* rpi = ref pi;
Console.WriteLine(i + " " + *pi + " " + *rpi); // "5 5 5"
pi = &j;
Console.WriteLine(i + " " + *pi + " " + *rpi); // "5 6 6"
The point of this admittedly pointless example code is that, although we didn't alter ref local variable rpi
itself in any way (since 'ya can't), it does now have a different (ultimate) referent.
More seriously, what ref local does now allow for, as far as tightening up the IL in array-indexing loop bodies, is a technique I call value-type stamping. This allows for efficient IL in loop bodies which need to access multiple fields of each element in an array of value-types. Typically, this has been a trade-off between external initialization (newobj
/ initobj
) followed by a single indexing access versus in-situ non-initialization but with the expense of redundant multiple runtime indexing.
With value-type stamping however, now we can entirely avoid per-element initobj
/ newobj
IL instructions and also have just a single indexing computation at runtime. I'll show the example first, and then describe the technique in general below.
/// <summary>
/// Returns a new array of (int,T) where each element of 'src' is paired with its index.
/// </summary>
public static (int Index, T Item)[] TagWithIndex<T>(this T[] src)
{
if (src.Length == 0)
return new (int, T)[0];
var dst = new (int Index, T Item)[src.Length]; // i.e, ValueTuple<int,T>[]
ref var p = ref dst[0]; // <-- co-opt element 0 of target for 'T' staging
ref int i = ref p.Index; // <-- index field in target will also control loop
i = src.Length;
while (true)
{
p.Item = src[--i];
if (i == 0)
return dst;
dst[i] = p;
}
}
The example shows a concise yet extreme use of the value-type stamping technique; you can discern its twist (given away in a comment) on your own if you're interested. In what follows, I'll instead discuss the value-type stamping technique in more general terms.
First, prepare ref locals with references directly to the relevant fields in a staging instance of the value-type. This can be either on the stack, or, as shown in the example, co-opted from the last-to-be-processed element of the target array itself. It may be valuable to have a ref
to the entire staging instance as well, especially if using the co-opting technique.
Each iteration of the loop body can then prepare the staging instance very efficiently, and as a final step when ready, "stamp" it wholesale into the array with only a single indexing operation. Of course, if the final element of the array was co-opted as the staging instance, then you can also leave the loop slightly earlier.