Merge pull request #115 from feO2x/issue-114-must-not-be-default-or-empty-for-immutable-array

Issue 114 must not be default or empty for immutable array

Author: feO2x

Code/Light.GuardClauses.AllProjects.sln

@@ -30,6 +30,11 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Versioning", "Versioning",
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Light.GuardClauses.SourceCodeTransformation.Tests", "Light.GuardClauses.SourceCodeTransformation.Tests\Light.GuardClauses.SourceCodeTransformation.Tests.csproj", "{A2067796-F167-47BE-B367-191152DCE230}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Plans", "Plans", "{664661A0-3861-486B-87B5-A35A5CC5F7B7}"
+	ProjectSection(SolutionItems) = preProject
+		Plans\issue-114-must-not-be-default-or-empty-for-immutable-array.md = Plans\issue-114-must-not-be-default-or-empty-for-immutable-array.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

Code/Light.GuardClauses.Tests/CollectionAssertions/MustNotBeDefaultOrEmptyTests.cs

@@ -0,0 +1,93 @@
+using System;
+using System.Collections.Immutable;
+using FluentAssertions;
+using Light.GuardClauses.Exceptions;
+using Xunit;
+
+namespace Light.GuardClauses.Tests.CollectionAssertions;
+
+public static class MustNotBeDefaultOrEmptyTests
+{
+    [Fact]
+    public static void ImmutableArrayDefault()
+    {
+        var defaultArray = default(ImmutableArray<int>);
+
+        Action act = () => defaultArray.MustNotBeDefaultOrEmpty(nameof(defaultArray));
+
+        var assertion = act.Should().Throw<EmptyCollectionException>().Which;
+        assertion.Message.Should()
+                 .Contain($"{nameof(defaultArray)} must not be an empty collection, but it actually is.");
+        assertion.ParamName.Should().BeSameAs(nameof(defaultArray));
+    }
+
+    [Fact]
+    public static void ImmutableArrayEmpty()
+    {
+        var emptyArray = ImmutableArray<string>.Empty;
+
+        Action act = () => emptyArray.MustNotBeDefaultOrEmpty(nameof(emptyArray));
+
+        var assertion = act.Should().Throw<EmptyCollectionException>().Which;
+        assertion.Message.Should()
+                 .Contain($"{nameof(emptyArray)} must not be an empty collection, but it actually is.");
+        assertion.ParamName.Should().BeSameAs(nameof(emptyArray));
+    }
+
+    [Fact]
+    public static void ImmutableArrayNotEmpty()
+    {
+        var array = ImmutableArray.Create("Foo", "Bar", "Baz");
+
+        array.MustNotBeDefaultOrEmpty().Should().Equal(array);
+    }
+
+    [Theory]
+    [MemberData(nameof(DefaultOrEmptyArrays))]
+    public static void CustomException(ImmutableArray<int> array) =>
+        Test.CustomException(
+            array,
+            (invalidArray, exceptionFactory) => invalidArray.MustNotBeDefaultOrEmpty(exceptionFactory)
+        );
+
+    [Fact]
+    public static void NoCustomExceptionThrown()
+    {
+        var array = ImmutableArray.Create(42, 84);
+        array.MustNotBeDefaultOrEmpty(_ => new ()).Should().Equal(array);
+    }
+
+    [Fact]
+    public static void CustomMessage() =>
+        Test.CustomMessage<EmptyCollectionException>(
+            message => ImmutableArray<string>.Empty.MustNotBeDefaultOrEmpty(message: message)
+        );
+
+    [Fact]
+    public static void CallerArgumentExpressionForEmptyArray()
+    {
+        var emptyArray = ImmutableArray<int>.Empty;
+
+        Action act = () => emptyArray.MustNotBeDefaultOrEmpty();
+
+        act.Should().Throw<EmptyCollectionException>()
+           .WithParameterName(nameof(emptyArray));
+    }
+
+    [Fact]
+    public static void CallerArgumentExpressionForDefaultArray()
+    {
+        var defaultArray = default(ImmutableArray<int>);
+
+        Action act = () => defaultArray.MustNotBeDefaultOrEmpty();
+
+        act.Should().Throw<EmptyCollectionException>()
+           .WithParameterName(nameof(defaultArray));
+    }
+
+    public static TheoryData<ImmutableArray<int>> DefaultOrEmptyArrays() => new ()
+    {
+        default,
+        ImmutableArray<int>.Empty,
+    };
+}

Code/Light.GuardClauses/Check.MustNotBeDefaultOrEmpty.cs

@@ -0,0 +1,53 @@
+using System;
+using System.Collections.Immutable;
+using System.Runtime.CompilerServices;
+using JetBrains.Annotations;
+using Light.GuardClauses.ExceptionFactory;
+
+namespace Light.GuardClauses;
+
+public static partial class Check
+{
+    /// <summary>
+    /// Ensures that the specified <see cref="ImmutableArray{T}" /> is not default or empty, or otherwise throws an <see cref="Exceptions.EmptyCollectionException" />.
+    /// </summary>
+    /// <param name="parameter">The <see cref="ImmutableArray{T}" /> to be checked.</param>
+    /// <param name="parameterName">The name of the parameter (optional).</param>
+    /// <param name="message">The message that will be passed to the resulting exception (optional).</param>
+    /// <exception cref="Exceptions.EmptyCollectionException">Thrown when <paramref name="parameter" /> is default or empty.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static ImmutableArray<T> MustNotBeDefaultOrEmpty<T>(
+        this ImmutableArray<T> parameter,
+        [CallerArgumentExpression("parameter")] string? parameterName = null,
+        string? message = null
+    )
+    {
+        if (parameter.IsDefaultOrEmpty)
+        {
+            Throw.EmptyCollection(parameterName, message);
+        }
+
+        return parameter;
+    }
+
+    /// <summary>
+    /// Ensures that the specified <see cref="ImmutableArray{T}" /> is not default or empty, or otherwise throws your custom exception.
+    /// </summary>
+    /// <param name="parameter">The <see cref="ImmutableArray{T}" /> to be checked.</param>
+    /// <param name="exceptionFactory">The delegate that creates your custom exception. The <see cref="ImmutableArray{T}" /> is passed to this delegate.</param>
+    /// <exception cref="Exception">Your custom exception thrown when <paramref name="parameter" /> is default or empty.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    [ContractAnnotation("exceptionFactory:null => halt")]
+    public static ImmutableArray<T> MustNotBeDefaultOrEmpty<T>(
+        this ImmutableArray<T> parameter,
+        Func<ImmutableArray<T>, Exception> exceptionFactory
+    )
+    {
+        if (parameter.IsDefaultOrEmpty)
+        {
+            Throw.CustomException(exceptionFactory, parameter);
+        }
+
+        return parameter;
+    }
+}

Code/Light.GuardClauses/Light.GuardClauses.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
     <Import Project="..\Version.props" />
 
@@ -39,10 +39,11 @@ Light.GuardClauses 13.0.0
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.0" Condition="'$(TargetFramework)' != 'net8.0'" />
-        <PackageReference Include="System.Memory" Version="4.6.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
-        <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="all" />
         <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="all" />
+      <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="all" />
+      <PackageReference Include="System.Collections.Immutable" Version="8.0.0" />
+      <PackageReference Include="System.Memory" Version="4.6.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
+      <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.0" Condition="'$(TargetFramework)' != 'net8.0'" />
     </ItemGroup>
 
     <ItemGroup>

Code/Plans/issue-114-must-not-be-default-or-empty-for-immutable-array.md

@@ -0,0 +1,18 @@
+# Issue 114 - MustNotBeDefaultOrEmpty for ImmutableArray
+
+## Context
+
+The .NET library Light.GuardClauses already has several assertions for collections. They often rely on `IEnumerable<T>` or `IEnumerable`. However, these assertions would result in `ImmutableArray<T>` being boxed - we want to avoid that by providing dedicated assertions for this type which avoids boxing. For this issue, we start out with a new assertion called `MustNotBeDefaultOrEmpty`.
+
+## Tasks for this issue
+
+- [ ] The production code should be placed in the Light.GuardClauses project. Create a file called `Check.MustNotBeDefaultOrEmpty.cs` in the root folder of the project.
+- [ ] In this file, create several extension method overloads called `MustNotBeDefaultOrEmpty` for `ImmutableArray<T>`. It should be placed in the class `Check` which is marked as `partial`.
+- [ ] Each assertion in Light.GuardClauses has two overloads - the first one takes the optional `parameterName` and `message` arguments and throw the default exception (in this case the existing `EmptyCollectionException`). The actual exception in thrown in the `Throw` class, you need to create a corresponding method for it in this class.
+- [ ] The other overload takes a delegate which allows the caller to provide their own custom exceptions. Pass the erroneous `ImmutableArray<T>` instance to the delegate and throw the returned exception.
+- [ ] Create unit tests for both overloads. The corresponding file should be placed in Light.GuardClauses.Tests project, in the existing subfolder 'CollectionAssertions'. Please follow conventions of the existing tests (e.g. use FluentAssertions' `Should()` for assertions).
+
+## Notes
+
+- There are already plenty of other assertions and tests in this library. All overloads are placed in the same file in the production code project. The test projects has top-level folders for different groups of assertions, like `CollectionAssertions`, `StringAssertions`, `DateTimeAssertions` and so on. Please take a look at them to follow a similar structure and code style.
+- If you have any questions or suggestions, please ask me about them.