Target netstandard2.0 instead of netstandard2.1
Picking up from #46 (closed), it would be best if this library could be used from legacy Framework projects, as well as the newer Core and Dotnet 5+ projects. After some investigation and research, instead of multi-targeting, the easiest way to accomplish this is to simply target netstandard2.0.
The project currently targets netstandard2.1, so this shouldn't break backwards compatibility, more projects should be able to consume the project after the change, not less, but still recommend holding the change off until a 2.0.0 release.
Using Newer Language Features
Downgrading to 2.0 from 2.1 moves the project to C# 7.3 and many of the newer language features aren't officially supported below C# 8.0. Some of these features can't be enabled, but most of the important ones can still be used.
The first step is adding a LangVersion element to the csproj file. This will tell the compiler to enable whatever newer language features it can.
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<LangVersion>9.0</LangVersion>
</PropertyGroup>Default Interface Implementations
These won't work. Period.
String.Create
This is the painful one. There is no string.Create() method in netstandard2.0. Unfortunately, there is also no easy workaround. The two options are rewrite the code to not use string.Create(), and endure any lose of performance that entails, or pick up a dependency on something like ZString.
The options could be mixed. Maybe multi-target 2.0 and 2.1, using string.Create() in the later and regular means in the former. On the other hand, as much string mucking as the library does, it might be beneficial to use ZString over and beyond its use in this case.
Using Declarations
These will be enabled by setting the LangVersion in the csproj file.
Spans and ReadOnlySpans
To use the Span and ReadOnlySpan classes, which the library does, the System.Memory package must be included.
Will also have to call AsSpan() on strings, because the default ReadOnlySpan<char> overloads don't exist. Can't directly parse a ReadOnlySpan<char> as an int, because Int32.TryParse(ReadOnlySpan<char>) and similar methods don't exist.
HashCode Generation
The HashCode classes doesn't exist in Standard 2.0. Have to reference Microsoft.Bcl.HashCode package.
Property Init Support
public WhateverType SomeProperty { get; init; }To support the init accessor on properties, the IsExternalInit class must be present. Since the class doesn't exist in netstandard2.0, we have to add ourselves.
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
//
// https://github.com/dotnet/runtime/blob/fb931c6fa65470899f811f8102523cf320ee7a50/src/libraries/Common/src/System/Runtime/CompilerServices/IsExternalInit.cs
//
// NOTICE: Included to enable C# 9 property init feature despite the project targeting netstandard2.0.
#if NETSTANDARD2_0 || NETSTANDARD2_1 || NETCOREAPP2_0 || NETCOREAPP2_1 || NETCOREAPP2_2 || NETCOREAPP3_0 || NETCOREAPP3_1 || NET45 || NET451 || NET452 || NET6 || NET461 || NET462 || NET47 || NET471 || NET472 || NET48
using System.ComponentModel;
// ReSharper disable once CheckNamespace
namespace System.Runtime.CompilerServices
{
/// <summary>
/// Reserved to be used by the compiler for tracking metadata.
/// This class should not be used by developers in source code.
/// </summary>
[EditorBrowsable(EditorBrowsableState.Never)]
internal static class IsExternalInit
{
}
}
#endif
Range Slicing Support
string fileExtensionNoDot = fileExtensionWithDot[1..];Supporting range slicing in netstandard2.0 requires adding 2 structs, Index and Range, as well as a helper class, RuntimeHelpers, with a GetSubArray() method.
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
//
// https://github.com/dotnet/runtime/blob/419e949d258ecee4c40a460fb09c66d974229623/src/libraries/System.Private.CoreLib/src/System/Index.cs
// https://github.com/dotnet/runtime/blob/419e949d258ecee4c40a460fb09c66d974229623/src/libraries/System.Private.CoreLib/src/System/Range.cs
//
// NOTICE: Included to enable C# 9 range slicing features despite the project targeting netstandard2.0.
#if NETSTANDARD2_0 || NETSTANDARD2_1 || NETCOREAPP2_0 || NETCOREAPP2_1 || NETCOREAPP2_2 || NETCOREAPP3_0 || NETCOREAPP3_1 || NET45 || NET451 || NET452 || NET6 || NET461 || NET462 || NET47 || NET471 || NET472 || NET48
#nullable enable
using System.Runtime.CompilerServices;
namespace System
{
/// <summary>Represent a type can be used to index a collection either from the start or the end.</summary>
/// <remarks>
/// Index is used by the C# compiler to support the new index syntax
/// <code>
/// int[] someArray = new int[5] { 1, 2, 3, 4, 5 } ;
/// int lastElement = someArray[^1]; // lastElement = 5
/// </code>
/// </remarks>
internal readonly struct Index : IEquatable<Index>
{
private readonly int _value;
/// <summary>Construct an Index using a value and indicating if the index is from the start or from the end.</summary>
/// <param name="value">The index value. it has to be zero or positive number.</param>
/// <param name="fromEnd">Indicating if the index is from the start or from the end.</param>
/// <remarks>
/// If the Index constructed from the end, index value 1 means pointing at the last element and index value 0 means pointing at beyond last element.
/// </remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public Index(int value, bool fromEnd = false)
{
if (value < 0)
{
throw new ArgumentOutOfRangeException(nameof(value), "value must be non-negative");
}
if (fromEnd)
{
this._value = ~value;
}
else
{
this._value = value;
}
}
// The following private constructors mainly created for perf reason to avoid the checks
private Index(int value)
{
this._value = value;
}
/// <summary>Create an Index pointing at first element.</summary>
public static Index Start => new Index(0);
/// <summary>Create an Index pointing at beyond last element.</summary>
public static Index End => new Index(~0);
/// <summary>Create an Index from the start at the position indicated by the value.</summary>
/// <param name="value">The index value from the start.</param>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Index FromStart(int value)
{
if (value < 0)
{
throw new ArgumentOutOfRangeException(nameof(value), "value must be non-negative");
}
return new Index(value);
}
/// <summary>Create an Index from the end at the position indicated by the value.</summary>
/// <param name="value">The index value from the end.</param>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Index FromEnd(int value)
{
if (value < 0)
{
throw new ArgumentOutOfRangeException(nameof(value), "value must be non-negative");
}
return new Index(~value);
}
/// <summary>Returns the index value.</summary>
public int Value
{
get
{
if (this._value < 0)
{
return ~this._value;
}
else
{
return this._value;
}
}
}
/// <summary>Indicates whether the index is from the start or the end.</summary>
public bool IsFromEnd => this._value < 0;
/// <summary>Calculate the offset from the start using the giving collection length.</summary>
/// <param name="length">The length of the collection that the Index will be used with. length has to be a positive value</param>
/// <remarks>
/// For performance reason, we don't validate the input length parameter and the returned offset value against negative values.
/// we don't validate either the returned offset is greater than the input length.
/// It is expected Index will be used with collections which always have non negative length/count. If the returned offset is negative and
/// then used to index a collection will get out of range exception which will be same affect as the validation.
/// </remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public int GetOffset(int length)
{
var offset = this._value;
if (this.IsFromEnd)
{
// offset = length - (~value)
// offset = length + (~(~value) + 1)
// offset = length + value + 1
offset += length + 1;
}
return offset;
}
/// <summary>Indicates whether the current Index object is equal to another object of the same type.</summary>
/// <param name="value">An object to compare with this object</param>
public override bool Equals(object? value) => value is Index && this._value == ((Index)value)._value;
/// <summary>Indicates whether the current Index object is equal to another Index object.</summary>
/// <param name="other">An object to compare with this object</param>
public bool Equals(Index other) => this._value == other._value;
/// <summary>Returns the hash code for this instance.</summary>
public override int GetHashCode() => this._value;
/// <summary>Converts integer number to an Index.</summary>
public static implicit operator Index(int value) => FromStart(value);
/// <summary>Converts the value of the current Index object to its equivalent string representation.</summary>
public override string ToString()
{
if (this.IsFromEnd)
{
return "^" + ((uint)this.Value).ToString();
}
return ((uint)this.Value).ToString();
}
}
/// <summary>Represent a range has start and end indexes.</summary>
/// <remarks>
/// Range is used by the C# compiler to support the range syntax.
/// <code>
/// int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
/// int[] subArray1 = someArray[0..2]; // { 1, 2 }
/// int[] subArray2 = someArray[1..^0]; // { 2, 3, 4, 5 }
/// </code>
/// </remarks>
internal readonly struct Range : IEquatable<Range>
{
/// <summary>Represent the inclusive start index of the Range.</summary>
public Index Start { get; }
/// <summary>Represent the exclusive end index of the Range.</summary>
public Index End { get; }
/// <summary>Construct a Range object using the start and end indexes.</summary>
/// <param name="start">Represent the inclusive start index of the range.</param>
/// <param name="end">Represent the exclusive end index of the range.</param>
public Range(Index start, Index end)
{
this.Start = start;
this.End = end;
}
/// <summary>Indicates whether the current Range object is equal to another object of the same type.</summary>
/// <param name="value">An object to compare with this object</param>
public override bool Equals(object? value) =>
value is Range r &&
r.Start.Equals(this.Start) &&
r.End.Equals(this.End);
/// <summary>Indicates whether the current Range object is equal to another Range object.</summary>
/// <param name="other">An object to compare with this object</param>
public bool Equals(Range other) => other.Start.Equals(this.Start) && other.End.Equals(this.End);
/// <summary>Returns the hash code for this instance.</summary>
public override int GetHashCode()
{
return this.Start.GetHashCode() * 31 + this.End.GetHashCode();
}
/// <summary>Converts the value of the current Range object to its equivalent string representation.</summary>
public override string ToString()
{
return this.Start + ".." + this.End;
}
/// <summary>Create a Range object starting from start index to the end of the collection.</summary>
public static Range StartAt(Index start) => new Range(start, Index.End);
/// <summary>Create a Range object starting from first element in the collection to the end Index.</summary>
public static Range EndAt(Index end) => new Range(Index.Start, end);
/// <summary>Create a Range object starting from first element to the end.</summary>
public static Range All => new Range(Index.Start, Index.End);
/// <summary>Calculate the start offset and length of range object using a collection length.</summary>
/// <param name="length">The length of the collection that the range will be used with. length has to be a positive value.</param>
/// <remarks>
/// For performance reason, we don't validate the input length parameter against negative values.
/// It is expected Range will be used with collections which always have non negative length/count.
/// We validate the range is inside the length scope though.
/// </remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public (int Offset, int Length) GetOffsetAndLength(int length)
{
int start;
var startIndex = this.Start;
if (startIndex.IsFromEnd)
{
start = length - startIndex.Value;
}
else
{
start = startIndex.Value;
}
int end;
var endIndex = this.End;
if (endIndex.IsFromEnd)
{
end = length - endIndex.Value;
}
else
{
end = endIndex.Value;
}
if ((uint)end > (uint)length || (uint)start > (uint)end)
{
throw new ArgumentOutOfRangeException(nameof(length));
}
return (start, end - start);
}
}
}
namespace System.Runtime.CompilerServices
{
internal static class RuntimeHelpers
{
/// <summary>
/// Slices the specified array using the specified range.
/// </summary>
public static T[] GetSubArray<T>(T[] array, Range range)
{
if (array == null)
{
throw new ArgumentNullException(nameof(array));
}
(int offset, int length) = range.GetOffsetAndLength(array.Length);
if (default(T) != null || typeof(T[]) == array.GetType())
{
// We know the type of the array to be exactly T[].
if (length == 0)
{
return Array.Empty<T>();
}
var dest = new T[length];
Array.Copy(array, offset, dest, 0, length);
return dest;
}
else
{
// The array is actually a U[] where U:T.
var dest = (T[])Array.CreateInstance(array.GetType().GetElementType(), length);
Array.Copy(array, offset, dest, 0, length);
return dest;
}
}
}
}
#endif
Edited by Jay Jeckel