Background

.NET is a managed platform, that means the memory access and management is safe and automatic. All types are fully managed by .NET, it allocates memory either on the execution stacks, or managed heaps.

In the event of interop or low-level development, you may want the access to the native objects and system memory, here is why the interop part comes, there are types that can marshal into the native world, invoke native APIs, convert managed/native types and define a native structure from the managed code.

Problem 1: Memory access patterns

In .NET world, there are three types of memory you may be interested:

• Managed heap memory, such as an array;
• Stack memory, such as objects created by stackalloc;
• Native memory, such as a native pointer reference.

Each type of memory access may need to use language features that are designed for it:

• To access heap memory, use the fixed (pinned) pointer on supported types (like string), or use other appropriate .NET types that have access to it, such as an array or a buffer;
• To access stack memory, use pointers with stackalloc;
• To access unmanaged system memory, use pointers with Marshal APIs.

You see, different access pattern needs different code, no single built-in type for all contiguous memory access.

Problem 2: Performance

In many applications, the most CPU consuming operations are string operations. If you run a profiler session against your application, you may find the fact that 95% of the CPU time is used to call string and related functions.

Trim, IsNullOrWhiteSpace, and SubString may be the most frequently used string APIs, and they are also very heavy:

• Trim() or SubString() returns a new string object that is part of the original string, this is unnecessary if there is a way to slice and return a portion of the original string to save one copy.
• IsNullOrWhiteSpace() takes a string object that needs a memory copy (because string is immutable.)
• Specifically,  string concatenation is expensive, it takes n string objects, makes n copy, generate n - 1 temporary string objects, and return a final string object, the n – 1 copies can be eliminated if there is a way to get direct access to the return string memory and perform sequential writes.

Span<T>

System.Span<T> is a stack-only type (ref struct) that wraps all memory access patterns, it is the type for universal contiguous memory access. You can think the implementation of the Span<T> contains a dummy reference and a length, accepting all 3 memory access types.

You can create a Span<T> using its constructor overloads or implicit operators from array, stackalloc’d pointers and unmanaged pointers.

// Use implicit operator Span<char>(char[]).
Span<char> span1 = new char[] { 's', 'p', 'a', 'n' };

// Use stackalloc.
Span<byte> span2 = stackalloc byte[50];

// Use constructor.
IntPtr array = new IntPtr();
Span<int> span3 = new Span<int>(array.ToPointer(), 1);

Once you have a Span<T> object, you can set value with a specified index, or return a portion of the span:

// Create an instance.
Span<char> span = new char[] { 's', 'p', 'a', 'n' };
// Access the reference of the first element.
ref char first = ref span[0];
// Assign the reference with a new value.
first = 'S';
// You get "Span".
Console.WriteLine(span.ToArray());

// Return a new span with start index = 1 and end index = span.Length - 1.
// You get "pan".
Span<char> span2 = span.Slice(1);
Console.WriteLine(span2.ToArray());

You can then use the Slice() method to write a high performance Trim() method:

private static void Main(string[] args)
{
    string test = "   Hello, World! ";
    Console.WriteLine(Trim(test.ToCharArray()).ToArray());
}

private static Span<char> Trim(Span<char> source)
{
    if (source.IsEmpty)
    {
        return source;
    }

    int start = 0, end = source.Length - 1;
    char startChar = source[start], endChar = source[end];

    while ((start < end) && (startChar == ' ' || endChar == ' '))
    {
        if (startChar == ' ')
        {
            start++;
        }

        if (endChar == ' ')
        {
            end—;
        }

        startChar = source[start];
        endChar = source[end];
    }

    return source.Slice(start, end - start + 1);
}

The above code does not copy over strings, nor generate new strings, it returns a portion of the original string by calling the Slice() method.

Because Span<T> is a ref struct, all ref struct restrictions apply. i.e. you cannot use Span<T> in fields, properties, iterator and async methods.

Memory<T>

System.Memory<T> is a wrapper of System.Span<T>, make it accessible in iterator and async methods. Use the Span property on the Memory<T> to access the underlying memory, this is extremely helpful in the asynchronous scenarios like File Streams and network communications (HttpClient etc..)

The following code shows simple usage of this type.

private static async Task Main(string[] args)
{
    Memory<byte> memory = new Memory<byte>(new byte[50]);
    int count = await ReadFromUrlAsync("https://www.microsoft.com", memory).ConfigureAwait(false);
    Console.WriteLine("Bytes written: {0}", count);
}

private static async ValueTask<int> ReadFromUrlAsync(string url, Memory<byte> memory)
{
    using (HttpClient client = new HttpClient())
    {
        Stream stream = await client.GetStreamAsync(new Uri(url)).ConfigureAwait(false);
        return await stream.ReadAsync(memory).ConfigureAwait(false);
    }
}

The Framework Class Library/Core Framework (FCL/CoreFx) will add APIs based on the span-like types for Streams, strings and more in .NET Core 2.1.

ReadOnlySpan<T> and ReadOnlyMemory<T>

System.ReadOnlySpan<T> is the read-only version of the System.Span<T> struct where the indexer returns a readonly ref object instead of ref object. You get read-only memory access when using System.ReadOnlySpan<T> readonly ref struct.

This is useful for string type, because string is immutable, it is treated as read-only span.

We can rewrite the above code to implement the Trim() method using ReadOnlySpan<T>:

private static void Main(string[] args)
{
    // Implicit operator ReadOnlySpan(string).
    ReadOnlySpan<char> test = "   Hello, World! ";
    Console.WriteLine(Trim(test).ToArray());
}

private static ReadOnlySpan<char> Trim(ReadOnlySpan<char> source)
{
    if (source.IsEmpty)
    {
        return source;
    }

    int start = 0, end = source.Length - 1;
    char startChar = source[start], endChar = source[end];

    while ((start < end) && (startChar == ' ' || endChar == ' '))
    {
        if (startChar == ' ')
     {
            start++;
        }

        if (endChar == ' ')
        {
            end—;
        }

        startChar = source[start];
        endChar = source[end];
    }

    return source.Slice(start, end - start + 1);
}

As you can see, Nothing is changed in the method body; I just changed the parameter type from Span<T> to ReadOnlySpan<T>, and used the implicit operator to convert a string literal to ReadOnlySpan<char>.

System.ReadOnlyMemory<T> is the read-only version of System.Memory<T> struct where the Span property is a ReadOnlySpan<T>. When using this type, you get read-only access to the memory and you can use it with an iterator method or async method.

Memory Extensions

The System.MemoryExtensions class contains extension methods for different types that manipulates with span types, here is a list of commonly used extension methods, many of them are the equivalent implementations for existing APIs using the span types.

• AsSpan, AsMemory: Convert arrays into Span<T> or Memory<T> or their read-only counterparts.
• BinarySearch, IndexOf, LastIndexOf: Search elements and indexes.
• IsWhiteSpace, Trim, TrimStart, TrimEnd, ToUpper, ToUpperInvariant, ToLower, ToLowerInvariant: Span<char> operations similar to string.

Memory Marshal

In some case, you probably want to have lower level access to the memory types and system buffers, and convert between spans and read-only spans. The System.Runtime.InteropServices.MemoryMarshal static class provides such functionalities to allow you control these access scenarios. The following code shows to title case a string using the span types, this is high performant because there is no temporary string allocations.

private static void Main(string[] args)
{
    string source = "span like types are awesome!";
    // source.ToMemory() converts source from string to ReadOnlyMemory<char>,
    // and MemoryMarshal.AsMemory converts ReadOnlyMemory<char> to Memory<char>
    // so you can modify the elements.
    TitleCase(MemoryMarshal.AsMemory(source.AsMemory()));
    // You get "Span like types are awesome!";
    Console.WriteLine(source);
}

private static void TitleCase(Memory<char> memory)
{
    if (memory.IsEmpty)
    {
        return;
    }

    ref char first = ref memory.Span[0];
    if (first >= 'a' && first <= 'z')
    {
        first = (char)(first - 32);
    }
}

Conclusion

Span<T> and Memory<T> enables a uniform way to access contiguous memory, regardless how the memory is allocated. It is very helpful for native development scenarios, as well as high performance scenarios. Especially, you will gain significant performance improvements while using span types to work with strings. It is a very nice feature innovated in C# 7.2.

NOTE: To use this feature, you will need to use Visual Studio 2017.5 and language version 7.2 or latest.

Background

In the previous posts, I have explained many new C# features, each of the feature is introduced to either enhance the language, or solve issues. Specifically, I explained value types and reference types, pass parameters by value, pass parameters by reference, ref locals and ref returns and in parameters. Many of these features are designed for high performance scenarios.

ref and in parameters can help to avoid copying values so that it reduces the allocation of memory. This is efficient when you have stack allocated local variables to pass as the actual parameters of a method, in this case, all the allocations are on the stack; no heap allocation is necessary.

For high performance and native development scenarios, you may want “stack-only”  types that always stay on execution stack, so operations against objects of this type can only happen on the stack, any external references to this type in the scopes that may expose to managed heap, should be disallowed.

Ref Struct

ref struct is the stack-only value type that:

• Represents a sequential struct layout;
• Can be used stack-only. i.e. method parameters and local variables;
• Cannot be static or instance members of a class or normal struct;
• Cannot be method parameter of async methods or lambda expressions;
• Cannot be dynamic binding, boxing, unboxing, wrapping or converting.

ref struct is also called embedded reference.

Examples

The following code defines a ref struct.

public ref struct MyRefStruct
{
    public int MyIntValue1;
    public int MyIntValue2;

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override bool Equals(object obj) => throw new NotSupportedException();

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override int GetHashCode() => throw new NotSupportedException();

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override string ToString() => throw new NotSupportedException();
}

Please note, I have overridden the Equals, GetHashCode and ToString methods that are inherited from System.Object.  Because boxing is not allowed for ref structs, you will have no way to call these two base methods.

You can use MyRefStruct as regular value type in method parameters or local variables, but you will not be able to use it elsewhere.

You can also make readonly ref structs, simply add readonly directive to the ref struct declaration.

public readonly ref struct MyRefStruct
{
    public readonly int MyIntValue1;
    public readonly int MyIntValue2;

    public MyRefStruct(int value1, int value2)
    {
        this.MyIntValue1 = value1;
        this.MyIntValue2 = value2;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override bool Equals(object obj) => throw new NotSupportedException();

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override int GetHashCode() => throw new NotSupportedException();

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override string ToString() => throw new NotSupportedException();
}

Like regular readonly structs, you need to make all instance fields/properties read-only.

Metadata

Ref struct is available in C# 7.2. This feature needs compiler level changes to work, to be backward compatible with previously  compiler generated assemblies,. C# 7.2 compiler emits [Obsolete] and [IsByRefLike] attributes for ref struct declarations.

If any old assemblies references library that contains ref struct types, the [Obsolete] attribute will effect and block the code from compiling.

Here is the generated IL for the above ref struct declaration.

.class public sequential ansi sealed beforefieldinit Demo.MyRefStruct
extends [System.Runtime]System.ValueType
{
.custom instance void [System.Runtime]System.Runtime.CompilerServices.IsByRefLikeAttribute::.ctor() = (
        01 00 00 00
    )
.custom instance void [System.Runtime]System.ObsoleteAttribute::.ctor(string, bool) = (
        01 00 52 54 79 70 65 73 20 77 69 74 68 20 65 6d
        62 65 64 64 65 64 20 72 65 66 65 72 65 6e 63 65
        73 20 61 72 65 20 6e 6f 74 20 73 75 70 70 6f 72
        74 65 64 20 69 6e 20 74 68 69 73 20 76 65 72 73
        69 6f 6e 20 6f 66 20 79 6f 75 72 20 63 6f 6d 70
        69 6c 65 72 2e 01 00 00
    )
.custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = (
        01 00 00 00
    )
// Fields
.field public initonly int32 MyIntValue1
.field public initonly int32 MyIntValue2
// Methods
.method public hidebysig specialname rtspecialname
instance void .ctor (
int32 value1,
int32 value2
        ) cil managed
    {
// Method begins at RVA 0x2090
// Code size 16 (0x10)
.maxstack 8
// (no C# code)
        IL_0000: nop
// this.MyIntValue1 = value1;
        IL_0001: ldarg.0
        IL_0002: ldarg.1
        IL_0003: stfld int32 Demo.MyRefStruct::MyIntValue1
// this.MyIntValue2 = value2;
        IL_0008: ldarg.0
        IL_0009: ldarg.2
        IL_000a: stfld int32 Demo.MyRefStruct::MyIntValue2
// (no C# code)
        IL_000f: ret
    } // end of method MyRefStruct::.ctor
.method public hidebysig virtual
instance bool Equals (
object obj
        ) cil managed
    {
// Method begins at RVA 0x20a1
// Code size 6 (0x6)
.maxstack 8
// throw new NotSupportedException();
        IL_0000: newobj instance void [System.Runtime]System.NotSupportedException::.ctor()
// (no C# code)
        IL_0005: throw
    } // end of method MyRefStruct::Equals
.method public hidebysig virtual
instance int32 GetHashCode () cil managed
    {
.custom instance void [System.Runtime]System.ComponentModel.EditorBrowsableAttribute::.ctor(valuetype [System.Runtime]System.ComponentModel.EditorBrowsableState) = (
            01 00 01 00 00 00 00 00
        )
// Method begins at RVA 0x20a8
// Code size 6 (0x6)
.maxstack 8
// throw new NotSupportedException();
        IL_0000: newobj instance void [System.Runtime]System.NotSupportedException::.ctor()
// (no C# code)
        IL_0005: throw
    } // end of method MyRefStruct::GetHashCode
.method public hidebysig virtual
instance string ToString () cil managed
    {
.custom instance void [System.Runtime]System.ComponentModel.EditorBrowsableAttribute::.ctor(valuetype [System.Runtime]System.ComponentModel.EditorBrowsableState) = (
            01 00 01 00 00 00 00 00
        )
// Method begins at RVA 0x20af
// Code size 6 (0x6)
.maxstack 8
// throw new NotSupportedException();
        IL_0000: newobj instance void [System.Runtime]System.NotSupportedException::.ctor()
// (no C# code)
        IL_0005: throw
    } // end of method MyRefStruct::ToString
} // end of class Demo.MyRefStruct

Span<T> and Memory<T>

With the support of ref-like types, it is now possible to have a consolidated type for all contiguous memory access. The System.Span<T>, which represents a sequential space of the memory, can be used for universal memory operations for execution stacks, managed heaps and unmanaged heaps.

Here is a simple usage of ReadOnlySpan<T> to trim the start spaces of a string.

internal class Program
{
    private static void Main(string[] args)
    {
        string text = "  I am using C# 7.2 Span<T>!";
        Console.WriteLine(TrimStart(text).ToArray());
    }

    private static ReadOnlySpan<char> TrimStart(ReadOnlySpan<char> text)
    {
        if (text.IsEmpty)
        {
            return text;
        }

        int i = 0;
        char c;

        while ((c = text[i]) == ' ')
        {
             i++;
        }

        return text.Slice(i);
    }
}

System.Memory<T> wraps the System.Span<T> so it can be used for async methods, which enables asynchronous scenarios for I/O bound and CPU bound operations. My next post will have more details.

Conclusion

C# 7.2 adds language features for high performance scenarios and enables efficiencies for lower native development and interoperability scenarios. Ref struct can also be used together with stackalloc, Span<T>, fixed buffers and Ranges (C# 7.3) for productivity.

NOTE: To use this feature, use Visual Studio 2017 15.5+.

Part 1: Value Tuples
Part 2: Async Main
Part 3: Default Literals
Part 4: Discards
Part 5: Private Protected
Part 6: Read-only structs
Part 7: Ref Returns
Part 8: (This post) “in” Parameters

Background

By default, method arguments are passed by value. That is, arguments are copied and passed into the method. Therefore, modification to the argument inside the method body does not affect the original value. In most of the cases, modifications are unnecessary.

Other programming languages, such as C++, has a const parameter or similar concept: This indicates that the parameter inside the method body is a constant that cannot be reassigned. It helps to avoid mistakes where you unintentionally reassign a method parameter in the body, and improves the performance by disallowing the unnecessary assignments.

C# 7.2 introduces the in parameter (aka. readonly ref parameter.) A method parameter with in modifier means that this parameter is by ref and read only within the method body.

in parameters

Let’s take the following method definition as an example.

public int Increment(int value)
{
    // Reassignment is ok, "value" is passed by value.
    value = value + 1;
    return value;
}

To make a readonly ref parameter, use the in modifier for a parameter.

public int Increment(in int value)
{
    // Reassignment is not ok, "value" is passed by ref and read-only.
    int returnValue = value + 1;
    return returnValue;
}

If you reassign value, the compiler will generate an error.

To call this method, use your normal way.

int v = 1;
Console.WriteLine(Increment(v));

Because value is read-only, you cannot put value in the left side (I.e. LValue.) Unary operators that does an assignment is also disallowed, such as ++ or –. However, you can still take the address of the value and modify using pointer operations.

Overload Resolutions

in is a modifier to a method parameter that indicates the ref kind of such parameter, it is considered as part of the method signature. That means you can have two method overloads that just differ by in modifier.

The following code example defines two method overloads, with just the ref kind different.

public class C
{
    public void A(int a)
    {
        Console.WriteLine("int a");
    }

    public void A(in int a)
    {
        Console.WriteLine("in int a");
    }
}

By default, the method call will resolve to use by value signature. To clear the ambiguity and explicitly call the by ref signature, put in before the actual argument when explicitly call the A(in int) method overload.

private static void Main(string[] args)
{
    C c = new C();
    c.A(1); // A(int)
    int x = 1;
    c.A(in x); // A(in int)
    c.A(x); // A(int)
}

The program output is as following.

Restrictions

Since in parameters are read-only ref parameters, all ref parameter limitations apply.

• Cannot apply with an iterator method (I.e. method that has yield statements.)
• Cannot apply with an async method
• If you mark the args of the Main method as in modifier, the method signature will become invalid for the entry point.

in parameter and the CLR

.NET already has a similar concept in CLR, so the in parameter feature does not require CLR changes.

Any in parameter will be compiled to MSIL with an additional [in] directive in the definition. To observe the compilation behavior, I use ILDAsm.exe to get the decompiled MSIL for the above example.

The following MSIL code is for method C.A(int):

.method public hidebysig instance void  A(int32 a) cil managed

{
   // Code size       13 (0xd)
   .maxstack  8
   IL_0000:  nop
   IL_0001:  ldstr      "int a"
   IL_0006:  call       void [System.Console]System.Console::WriteLine(string)
   IL_000b:  nop
   IL_000c:  ret

} // end of method C::A

The following MSIL code is for method C.A(in int):

.method public hidebysig instance void  A([in] int32& a) cil managed

{
   .param [1]
   .custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = ( 01 00 00 00 ) 
   // Code size       13 (0xd)
   .maxstack  8
   IL_0000:  nop
   IL_0001:  ldstr      "in int a"
   IL_0006:  call       void [System.Console]System.Console::WriteLine(string)
   IL_000b:  nop
   IL_000c:  ret

} // end of method C::A

Do you see the difference? int32& shows it is a by ref parameter; [in] is an additional metadata that instructs the CLR how to deal with this parameter.

The below code is the MSIL for the Main method in the above example, it shows how to call these two C.A() method overloads.

.method private hidebysig static void  Main(string[] args) cil managed

{
   .entrypoint
   // Code size       35 (0x23)
   .maxstack  2
   .locals init (class Demo.C V_0,
            int32 V_1)
   IL_0000:  nop
   IL_0001:  newobj     instance void Demo.C::.ctor()
   IL_0006:  stloc.0
   IL_0007:  ldloc.0
   IL_0008:  ldc.i4.1
   IL_0009:  callvirt   instance void Demo.C::A(int32)
   IL_000e:  nop
   IL_000f:  ldc.i4.1
   IL_0010:  stloc.1
   IL_0011:  ldloc.0
   IL_0012:  ldloca.s   V_1
   IL_0014:  callvirt   instance void Demo.C::A(int32&)
   IL_0019:  nop
   IL_001a:  ldloc.0
   IL_001b:  ldloc.1
   IL_001c:  callvirt   instance void Demo.C::A(int32)
   IL_0021:  nop
   IL_0022:  ret

} // end of method Program::Main

From the call site, there is no additional metadata to instruct to call C.A(in int).

in parameter and the Interop

There are many places where the [In] attributes are used to match with the native method signature for the interoperability. Let’s take the following Windows API as an example.

[DllImport("shell32")]
public static extern int ShellAbout(
    [In] IntPtr handle,
    [In] string title,
    [In] string text,
    [In] IntPtr icon);

The corresponding MSIL for this method is as below.

.method public hidebysig static pinvokeimpl("shell32" winapi) 
         int32  ShellAbout([in] native int handle,
                           [in] string title,
                           [in] string text,
                           [in] native int icon) cil managed preservesig

If we change the ShellAbout signature to use in parameter:

[DllImport("shell32")]
public static extern int ShellAbout(
    in IntPtr handle,
    in string title,
    in string text,
    in IntPtr icon);

The generated MSIL for this method is:

.method public hidebysig static pinvokeimpl("shell32" winapi) 
         int32  ShellAbout([in] native int& handle,
                           [in] string& title,
                           [in] string& cext,
                           [in] native int& icon) cil managed preservesig

{
   .param [1]
   .custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = ( 01 00 00 00 ) 
   .param [2]
   .custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = ( 01 00 00 00 ) 
   .param [3]
   .custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = ( 01 00 00 00 ) 
   .param [4]
   .custom instance void [System.Runtime]System.Runtime.CompilerServices.IsReadOnlyAttribute::.ctor() = ( 01 00 00 00 ) 

}

As you can see, the compiler emits code for each in parameter with [in] directive, ref data type and also [IsReadOnly] attribute. Since the parameter has changed from by value to by ref, the P/Invoke may fail due to the mismatch of the original signature.

Conclusion

in parameter is a great feature that extends the C# language, it is easy to use and it is binary compatible (no CLR change required.) Read-only ref parameters help to avoid mistakes by giving a compile time error when modifying the read only parameter. This feature can be used with other ref features such as ref returns and ref structs.

Part 1: Value Tuples
Part 2: Async Main
Part 3: Default Literals
Part 4: Discards
Part 5: Private Protected
Part 6: Read-only structs
Part 7: (This post) Ref Returns

Background

There are two ways to pass an value into a method:

1. Pass by value. When an argument is passed into a method, a copy of the argument (if it is a value type) or a copy of the argument reference (if it is a reference type) is passed. When you change the argument in the method, the changes (single assignment or compound assignments) is reflected to the copy of the argument/argument reference and it is not reflected to the argument or argument reference itself. This is the default Way in .NET languages (ByVal in Visual Basic.)
2. Pass by reference. When an argument is passed into a method, either the argument itself (if it is a value type) or the argument reference (if it is a reference type) is directly passed. No other copies are generated. When you change the argument in the method, the changes (single assignment or compound assignments) will reflect to the argument or argument reference itself. This is indicated by using ref keyword in C# or ByRef keyword in Visual Basic.

For example, the FCL’s Array.Resize() method takes a ref parameter of type Array, this ref value is modified in the method implementation to point to the new space of the array after the resize. You will be able to continue using the variable for that array and access the new space:

byte[] data = new byte[10];
Array.Resize(ref data, 20);
Console.WriteLine($"New array size is: {data.Length}");

Method can also return a value to the caller, but before C# 7.0, all returns are by value by default.

With C# 7.0 or later, ref returns are supported.

Ref Returns

Ref Returns are method return values by references. Similar to ref values passed as method arguments, ref returns can be modified by the caller, and any changes (assignments) to the value will reflect to the original value returned from the method.

In C#, you can make a ref return using the return ref keywords.

Please see the following example.

private static ref T ElementAt<T>(ref T[] array, int position)
{
     if (array == null)
     {
         throw new ArgumentNullException(nameof(array));
     }

     if (position < 0 || position >= array.Length)
     {
         throw new ArgumentOutOfRangeException(nameof(position));
     }

     return ref array[position];
}

The purpose of the above method is to obtain a reference to the element at the specific position of an array. Later you can use this reference to change the value of the element; because it is a ref value, the changes will apply to the original value in the array.

To use this method, use ref locals:

private static void Main(string[] args)
{
    int[] data = new int[10];
    Console.WriteLine($"Before change, element at 2 is: {data[2]}");
    ref int value = ref ElementAt(ref data, 2);
    // Change the ref value.
    value = 5;
    Console.WriteLine($"After change, element at 2 is: {data[2]}");
}

The Visual Studio IntelliSense will indicate the calling method is a ref return method.

The output of this code is as below:

Call Methods with Ref Returns

As previous example, to get a reference of a ref return value, you will need to use ref locals and also put the ref keyword in front of the method (ref in both left and right.)

ref int value = ref ElementAt(ref data, 2);

You can also call this method without the ref keyword, making the value returned by value.

int value = ElementAt(ref data, 2);

In this case, the program output will be as the following:

However, you need either specify ref in both sides, or not have ref in both sides; you cannot specify ref in one side and not specify ref in the other side.

Additionally, the following code also works:

ElementAt(ref data, 2) = 5;

You will get the same output as the first example. The element at the position 2 is changed from 0 (default value) to 5. This works because the ref returns can appear as an LValue.

Overload Resolutions

Because return type is not part of method signature to consider an overload, the following method definitions may not work.

public int M(int[] value);
public ref int M(int[] value);

But the following definitions will work, because the parameter is by ref in the first method and is by value in the second method.

public ref int M(ref int[] value);
public ref int M(int[] value);

Therefore, in order to overload a ref return method, you’ll need to satisfy the parameter rules:

• Use different count of parameters, or
• Use different type of parameters, or
• Use different value passing method (by value or by ref) of parameters.

Restrictions

There are certain restrictions apply.

1. The value to be ref returned in a method must be a ref local; the source of this ref local can be an actual ref/out argument of this method, or a field in the type where the method is declared.
2. You cannot ref return a void type.
3. You cannot ref return a null literal. But you can ref return a ref local whose value is null.
4. You cannot ref return from an async method, because the return value might be uncertain by the time the async method returns.
5. Constants and enums are not allowed to be ref returned.

Conclusion

Ref returns is an extension of the C# language, it can improve the performance of the code by reducing the possibility of copying values from method returns. This is useful for those low level programming components such as interoperability, cross-platform, or resource constrained scenarios (Mobile, IoT etc.,) This feature requires no CLR changes because the similar concepts already exist. To use this feature, you will need to use C# language 7.0, by upgrading your Visual Studio version to 2017 or later.

Part 1: Value Tuples
Part 2: Async Main
Part 3: Default Literals
Part 4: Discards
Part 5: Private Protected
Part 6: (This article) Read-only structs

Background

In .NET world, there are two basic types: reference types and value types. To be short, Reference types are classes that can be inherited/extended, when passing reference type objects, a “pointer” is passed; value types are structs that cannot be inherited/extended, when passing value type objects, a “copy” is passed.

A struct in C# is a value type, and it is “internally inherited” from System.ValueType. (I said no inheritance between structs.)

When use structs in arguments, a copy of the struct is generated, using structs may be efficient because it reduces the times for heap object allocation.

In many scenarios, developers use structs as an efficient way to pass values, such as a return object from a method, or a basic data structure that would be used across the application.

Read-only structs

A read-only struct is a struct whose public members are read-only, as well as the “this” parameter.

Take a look at the following declaration:

public struct S
{
    public int Age { get; set; }
    public string Name { get; set; }

    public S(int age, string name)
    {
        this.Age = age;
        this.Name = name;
    }

    public S(S other)
    {
        this = other;
    }

    public S Replace(S other)
    {
        S value = this;
        this = other;
        return value;
    }
}

As you can see, I get full access to the declared property Age and Name, I also get access to this parameter so I can replace the instance with another instance of S.

If I add the readonly modifier to the declaration, My access will be limited:

• All members (properties, fields) must be read-only;
• I’ll need to initialize the members in the public parameterized constructor;
• “this” parameter will be read-only in other place except in constructor.
• You cannot define “field-like” events;

The below screenshot shows what things need to be fixed for the readonly struct.

Below is the fixed code:

public readonly struct S
{
    public int Age { get; }
    public string Name { get; }

    public S(int age, string name)
    {
        this.Age = age;
        this.Name = name;
    }

    public S(S other)
    {
        this = other;
    }
}

You can initialize new instances of S as you usually do. But then you cannot modify any members with any instance. You should always call the parameterized (not parameterless) constructor in order to initialize the instance object properly, otherwise you will get a default initialization of the instance (all members are defaulted to initial values of the member type.)

private static void Test()
{
    S s = new S(18, "Anna");
    ref S other = ref s;
    other = new S(other);
    bool equal = s.Equals(other); // true.
}

Conclusion

Read-only structs is a convenient feature that can help to protect your values from unintended modifications outside of your control; in combination with other new features (for example, ref structs and in parameters,) it will make your C# code targeting to low level programming easier. In the next few posts, I will explain all these new things. Please note that you will need C# 7.2 to work with this feature, which is available in Visual Studio 2017.5 Preview 4 or later.]]> https://docs.microsoft.com/archive/blogs/mazhou/c-7-series-part-5-private-protected Thu, 05 Oct 2017 03:34:28 GMT https://blogs.msdn.microsoft.com/mazhou/?p=355 C# has several accessibility modifiers, public, internal, internal protected, and private.

• Public: The member declared with this accessibility can be visible within the assembly containing this member, or any other assembly that references the containing assembly. i.e., access is not limited.
• Internal: The member declared with this accessibility can be visible within the assembly containing this member, it is not visible to any assembly outside of the containing assembly. i.e., access is limited to containing assembly only.
• Protected: The member declared with this accessibility can be visible within the types derived from the containing type within the containing assembly, and the types derived from the containing type outside of the containing assembly. i.e., access is limited to derived types of the containing type.
• Internal Protected: The member declared with this accessibility can be visible within the types derived from the containing type within or outside of the containing assembly, it is also visible to any types within the containing assembly. i.e., access is limited to containing assembly or derived types.
• Private: The member declared with this accessibility can be visible within the containing type, it is not visible to any derived types, other types in the same assembly or types outside of the containing assembly. i.e., access is limited to the containing type only.

Private Protected

C# 7.2 is adding a new level of accessibility: private protected. This is to match the same access level that has already been in the CLR.

• Private Protected: The member declared with this accessibility can be visible within the types derived from this containing type within the containing assembly. It is not visible to any types not derived from the containing type, or outside of the containing assembly. i.e., the access is limited to derived types within the containing assembly.

This is very helpful if developers want to implement something only visible to internal assembly level.

Example

To demonstrate the behavior of private protected, I created one solution that contains two projects: one is a Library project, another is a Console App project referencing the Library project. I created types within the Library project:

public class Base
{
     protected private void M()
     {
         Console.WriteLine("From Base.M()");
     }
}
 
public class D1 : Base
{
     new public void M()
     {
         Console.WriteLine("From D1.M()");
         base.M();
     }
}

In the Base class, I declared a private protected member M(), then in the D1 class that is derived from Base, I created a method M() and call base.M() internally. These two types are within the same assembly, so I should have access to base.M() from D1.

I then created another class C:

public class C
{
    public void M()
    {
        Base b = new Base();
        b.M();

        D1 d = new D1();
        d.M();
    }
}

I was trying to call b.M() in C.M() method, because C is not derived from Base, I don’t have the access to Base.M(), hence the code will not work; I saw this compilation error.

Lastly, I created a type in the Console App project that is not the containing assembly for Base. If I tried to access Base.M() there, I would be given this compilation error:

NOTE: To make this work, you will need to upgrade your project to C# 7.2 or latest,

Conclusion

Now with C# 7.2, we have five levels of accessibility: public, internal, protected, internal protected, and private protected. The addition of private protected will benefit from limiting the access to only derived types within the containing assembly to have special internal implementation for some members. Read more on this Private Protected page for more details.

bool parsedValue;
if (bool.TryParse("TRUE", out parsedValue)) { /* Do your stuff */ }

Here we want to ignore parsedValue. We also want to make this variable inaccessible so developers cannot reference it.

The C# 7.0 has a new feature called discards, which can be used to achieve our goal for this scenario.

Discards

Discards are local variables which you can assign but cannot read from. i.e. they are “write-only” local variables. They don’t have names, instead, they are represented as a _ (underscore.) _ is a contextual keyword, it is very similar to var, and _ cannot be read (i.e. cannot appear on the right side of an assignment.)

If we apply the discard to above code, it will look like this:

if (bool.TryParse("TRUE", out bool _)) { /* Do your stuff */ }

Because _ is unreadable, it will not appear in IntelliSense nor compile the code.

Places Discards Are Applicable

• A declaration expression with an out modifier, for example: bool.TryParse(“string”, out _)
• Pattern matching clauses, such as case int _ or if (x is string _)
• Deconstructions:
• In declaration: such as var (a, _, c) = myObj
• In assignment: such as var a, b; (a, b) = myObj
• Value Tuple deconstructions: such as var (a, _, _) = (1, 2, 3)

The _ Keyword

Please always remember that the _ is a contextual keyword, like var, that means if you have already declared a local variable _ in the current context and it is in scope, the _ will not be a discard and will refer to that local variable in scope.

More interestingly, look the following code:

bool _ = false, v = false;
if (bool.TryParse("TRUE", out var _))
{
     /* Do your stuff */
     v = _;
}

What is the value of v?

The answer is false. The if test is true, and string “TRUE” can parse as a Boolean value true, but we have out var _, this overrides the scope of the previously declared variable _, and it is a discard. Then the assignment v = _ inside if statement just reads the value of previously declared local variable _ (which is false,) and assigns to v, hence the value of v is false. If we remove the var to change the code to out _, the value of v will be true because _ is on longer a discard and it holds the value of the parsed Boolean.

Conclusion

The discards in C# enables a way to ignore some local variables, it is a design time feature, the local variable may still be required at runtime and compiler may also generate a name for it. Since the _ keyword is a contextual keyword, you need to set a code policy to avoid declaring local variables with the name _ to reduce confusions. This feature is compatible with previous versions of .NET platforms as it does not require a CLR change.

The default value of a type is either:

• null, if the type is a reference type, or
• an instance of the type constructed with the parameterless constructor, if the type is a value type.

The following screenshot is a quick example.

However, you can not have a default expression for any open type (Note: An open type is a type that has unbound type arguments; a type has all bound type arguments is called closed type), for example:

Now, if we want to use default value for a generic type in a method, we have to write code like this:

public static void Method(ImmutableArray<int> array) { }
 
public static void Main(string[] args)
{     
    Method(default(ImmutableArray<int>));
}

Do you see a redundant here? the compiler should know the exact type needed for the Method() for the first parameter. A default literal without the type specification should be sufficient enough.

Default Literals

C# 7.1 allows the default expressions. If compile with the C# language version 7.1, or latest, you can simplify the code as the following:

public static void Method(ImmutableArray<int> array) { }
public static void Main(string[] args)
{ 
    Method(default);
}

Now you get a clean code!

Similarly, you can have default literals for all the place that default(…) can appear:

public static void Main(string[] args = default)    // Default value for the optional parameter        {
    int i = default;        // Default value (0) for type System.Int32 
    string s = default;     // Default value (null) for type System.String 
    Method(default);        // Calling a method with default value for an argument 
    T t = default;          // Default value for a type parameter 
    return default;         // Default return value for a method that does not return void 
}

You can have default literals in a condition test:

int x = 2; 
if (x == default) { }       // Test if x is default value (0) of the type System.Int32 
if (x is default) { }       // Same as above

More interestingly, you can use default literals in switch…case. Oh, cool! but… wait, how about the label ‘case default’? Here is what I get from the IDE:

And if you apply the fix, it will be:

int x = 2; 
switch (x) 
{ 
    case (default): break; 
    default: break; 
}

This looks confusing, but at least we get live analytics about this, Thanks Roslyn!

The last thing I want to call out is there are cases that cannot apply default literals, for example:

// Error: 'as' must have reference type 
default as int; 
// OK. But the left hand expression is always null.
if (default as string == string.Empty) { }
// Error. Cannot apply operator 'is' to type 'default'.
if (default is string) { }

Conclusion

Default literals in C# 7.1 avoids redundant typing where the default value is known to compiler. This is a syntactical improvement and nothing changed for the CLR, The new code is 100% compatible with the code built by earlier versions of the C# compiler.

Application types that (must) have an entrypoint: Windows Forms App, UWP App, Console App, WPF App, ASP.NET and ASP.NET Core App and Xamarian App.

Application types that do not need an entrypoint: Class Library (/t:lib), Modules (/t:module).

The Main Method

Like other languages, C# program starts with the Main method. There are four overloads that are considered as the valid signatures for the Main method.

public static void Main();
public static int Main();
public static void Main(string[] args);
public static int Main(string[] args);

The C# entrypoint method must be static, name of the method must be Main, return type of this method can be either void or int, it can have one parameter of a string array, containing any command-line arguments.

If the entrypoint returns an int, then the value can be evaluated by the Operating System, or the host process that started the program with this entrypoint, this is widely used in the native world (such as to indicate successful launch of an external app.)

The Async Main Method

C# introduced async/await pattern in version 5.0 (with .NET Framework 4.5), allowing easy-to-read workflow for an asynchronous operation. Many existing language constructs for those async operations (aka. async programming models) can work with the new async/await keywords. Today, community develops many libraries that only provide async version of the operations. (for example, System.Net.HttpClient, Microsoft.Azure.EventHub.Core.)

As I showed above, if you want to await an async operation in the entrypoint method, you need to apply some workaround, because the following entrypoint definition is invalid:

public static async Task Main(string[] args) 
{ 
    await BuildWebHost(args).RunAsync(); 
}

The workaround would be synchronously wait for the operation.

public static void Main(string[] args)
{     
    BuildWebHost(args).RunAsync().GetAwaiter().GetResult();
}

Or calling Wait() on the Task object:

public static void Main(string[] args)
{
    BuildWebHost(args).RunAsync().Wait();
}

In C# 7.1, the language extends the valid signatures of an entrypoint to allow these async overloads of the Main method to be valid.

public static void Main();
public static int Main();
public static void Main(string[] args);
public static int Main(string[] args);
public static Task Main();
public static Task<int> Main();
public static Task Main(string[] args);
public static Task<int> Main(string[] args);

A Task-like return type enables the await keyword with the async modifier in the entrypoint method.

Conclusion

The Async Main makes the asynchronous operations in the entrypoint method easier to use, without any workaround, like it runs in other async methods. In the compiler time, Any async Main method will be wrapped as a non-async Main method that can be accepted by the CLR Host. Since this feature does not correspond to a CLR code change, the async Main method is just a syntactical sugar. This design allows backend compatibility with the previous versions of the language. To read more details, please see Async Main in the Roslyn Git repo.

Tuples

The System.Tuple class provides a type to represent a key-value like property bag. It can be used where you want to have a data structure to hold an object with properties (elements) but you don’t want to create a separate type for it. The following code shows how you use it as a return value of a method that holds the name and the age of a student.

public Tuple<string, int> GetStudentInfo(string id)
{     
    // Search by ID and find the student.
    return new Tuple<string, int>("Annie", 25);
}

As you can see, I am returning an instance of Tuple<string, int> object with first argument is the name and the second argument is the age. Later on we can have code to call this method, like this:

public void Test()
{     
    Tuple<string, int> info = GetStudentInfo("100-000-1000");
    Console.WriteLine($"Name: {info.Item1}, Age: {info.Item2}");
}

You can access name and age by referencing Item1 and Item2.

The Tuple class has some obvious problems:

• You need to access the properties with a name pattern ItemX, the property name may not make sense to the caller, that would be better if we can write something like info.Name and info.Age instead of info.;Item1 and info.Item2.
• You are limited to have maximum 8 properties. If you want more, the last type argument must be another Tuple. This makes the syntax super hard to understand.
• Tuple is a reference type, not like other primitive types (they are most value types), it allocates on heap and it could be too much object creation/allocation for CPU intensive operations.

Value Tuples

C# 7.0 introduced ValueTuple structure, which is a value type representation of the tuple object. The language team made many good things for this value tuple type, including a new syntax and many features (such as deconstruction.)

The following is a rewrite version with the value tuples, Note that if you don’t see the ValueTuple available in your project, you have to download the System.ValueTuple 4.3.0 NuGet package to your project. You don’t need to do anything if you are using .NET Framework 4.7 or higher, or .NET Standard Library 2.0 or higher.

public (string, int) GetStudentInfo(string id)
{
    // Search by ID and find the student. 
    return ("Annie", 25);
}
 
public void Test()
{ 
    (string, int) info = GetStudentInfo("100-000-1000"); 
    Console.WriteLine($"Name: {info.Item1}, Age: {info.Item2}");
}

The code above is much simplified by using the first-class syntax ().

You can even give a name to every element in the value tuple, like this:

public (string name, int age) GetStudentInfo(string id)
{
    // Search by ID and find the student.
    return (name: "Annie", age: 25);
}
 
public void Test()
{
    (string name, int age) info = GetStudentInfo("100-000-1000"); 
    Console.WriteLine($"Name: {info.name}, Age: {info.age}");
}

Perfect! Now you have good metadata for the elements in tuple objects, you then don’t need to go back and forth to make sure you are returning/accessing elements in the right order as its original definition.

The Visual Studio IDE will give you hints when you work with the value tuples.

Value Tuple Deconstruction

You can deconstruct the elements from the value tuple object, and access the local variables.

// Deconstruct using the var (x, y) syntax,
// or (var x, var y) syntax.
var (name, age) = GetStudentInfo("100-000-1000");
// Now you have two local variables: name and age.
Console.WriteLine($"Name: {name}, Age: {age}");

If you just care about certain elements but not all, you can use the _ keyword to ignore the local variable.

// Deconstruct using the var (x, y) syntax,
// or (var x, var y) syntax.
var (name, _) = GetStudentInfo("100-000-1000");
// Now you have just one local variable: name. The value for age is ignored.
Console.WriteLine($"Name: {name}");

Value Tuples to Tuples

The System.Tuple and System.ValueTuple provides some extension methods to help convert between Tuple and ValueTuple.

var valueTuple = (id: 1, name: "Annie", age: 25, dob: DateTime.Parse("1/1/1993"));
var tuple = valueTuple.ToTuple();

Conclusion

ValueTuple makes the C# language more modern, and easy to use with simplified syntax. It solves many Tuple problems:

• Value Tuple objects have first class syntax support, it simplifies the code to work with tuple elements.
• You can associate a name with the value tuple element, you get some level of design time and compiler time validation of your code.
• Please NOTE that the name associated with the tuple element is not a runtime metadata, i.e. there is no such a property/field with the name on the actual instance of that value tuple object, the property names are still Item1, Item2, etc., all element names are design time and compiler time only.
• You are now flexible to access all tuple elements, or some of them, by using the deconstruction and the _ keyword.
• Value Tuple types are value types, no inheritance or other features, this means that the value tuples are better performance.

Since the name of the value tuple element is not runtime, you have to be careful using it when doing serialization with existing libraries, such as Newtonsoft.Json, Unless the library updated to support the new metadata (TupleElementNameAttribute etc.) before then you would run into bugs.