feat: add MustContain for ImmutableArray

Signed-off-by: Kenny Pflug <kenny.pflug@live.de>

Author: feO2x

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

@@ -1,5 +1,6 @@
-using System;
+using System;
 using System.Collections.Generic;
+using System.Collections.Immutable;
 using System.Collections.ObjectModel;
 using FluentAssertions;
 using Light.GuardClauses.Exceptions;
@@ -69,4 +70,72 @@ public static void CallerArgumentExpression()
         act.Should().Throw<MissingItemException>()
            .WithParameterName(nameof(array));
     }
+
+    [Theory]
+    [InlineData(new[] { 1, 2, 3 }, 5)]
+    [InlineData(new[] { -5491, 6199 }, 42)]
+    public static void ImmutableArrayItemNotPartOf(int[] source, int item)
+    {
+        var immutableArray = source.ToImmutableArray();
+        Action act = () => immutableArray.MustContain(item, nameof(immutableArray));
+
+        var assertion = act.Should().Throw<MissingItemException>().Which;
+        assertion.Message.Should().Contain($"{nameof(immutableArray)} must contain {item}, but it actually does not.");
+    }
+
+    [Theory]
+    [InlineData(new[] { "Foo", "Bar" }, "Foo")]
+    [InlineData(new[] { "Foo", "Bar", "Foo" }, "Foo")]
+    [InlineData(new[] { "Qux" }, "Qux")]
+    [InlineData(new[] { "Qux", null }, null)]
+    public static void ImmutableArrayItemPartOf(string[] source, string item)
+    {
+        var immutableArray = source.ToImmutableArray();
+        immutableArray.MustContain(item).Should().Equal(immutableArray);
+    }
+
+    [Fact]
+    public static void ImmutableArrayEmptyDoesNotContainItem()
+    {
+        var immutableArray = ImmutableArray<string>.Empty;
+        Action act = () => immutableArray.MustContain("Foo");
+
+        act.Should().Throw<MissingItemException>();
+    }
+
+    [Theory]
+    [InlineData(new[] { 42L, 100L }, 1337L)]
+    public static void ImmutableArrayCustomException(long[] source, long item)
+    {
+        var immutableArray = source.ToImmutableArray();
+        Test.CustomException(
+            immutableArray,
+            item,
+            (array, i, exceptionFactory) => array.MustContain(i, exceptionFactory)
+        );
+    }
+
+    [Fact]
+    public static void ImmutableArrayCustomExceptionNotThrown()
+    {
+        var immutableArray = ImmutableArray.Create(1, 2, 3);
+        immutableArray.MustContain(2, (_, _) => new Exception()).Should().Equal(immutableArray);
+    }
+
+    [Fact]
+    public static void ImmutableArrayCustomMessage() =>
+        Test.CustomMessage<MissingItemException>(
+            message => ImmutableArray<string>.Empty.MustContain("Foo", message: message)
+        );
+
+    [Fact]
+    public static void ImmutableArrayCallerArgumentExpression()
+    {
+        var immutableArray = ImmutableArray.Create("Foo", "Bar");
+
+        var act = () => immutableArray.MustContain("Baz");
+
+        act.Should().Throw<MissingItemException>()
+           .WithParameterName(nameof(immutableArray));
+    }
 }

Code/Light.GuardClauses/Check.MustContain.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Collections.Immutable;
 using System.Linq;
 using System.Runtime.CompilerServices;
 using JetBrains.Annotations;
@@ -197,4 +198,50 @@ public static string MustContain(
 
         return parameter;
     }
+
+    /// <summary>
+    /// Ensures that the immutable array contains the specified item, or otherwise throws a <see cref="MissingItemException" />.
+    /// </summary>
+    /// <param name="parameter">The immutable array to be checked.</param>
+    /// <param name="item">The item that must be part of the immutable array.</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="MissingItemException">Thrown when <paramref name="parameter" /> does not contain <paramref name="item" />.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static ImmutableArray<T> MustContain<T>(
+        this ImmutableArray<T> parameter,
+        T item,
+        [CallerArgumentExpression("parameter")] string? parameterName = null,
+        string? message = null
+    )
+    {
+        if (!parameter.Contains(item))
+        {
+            Throw.MissingItem(parameter, item, parameterName, message);
+        }
+
+        return parameter;
+    }
+
+    /// <summary>
+    /// Ensures that the immutable array contains the specified item, or otherwise throws your custom exception.
+    /// </summary>
+    /// <param name="parameter">The immutable array to be checked.</param>
+    /// <param name="item">The item that must be part of the immutable array.</param>
+    /// <param name="exceptionFactory">The delegate that creates your custom exception. <paramref name="parameter" /> and <paramref name="item" /> are passed to this delegate.</param>
+    /// <exception cref="Exception">Your custom exception thrown when <paramref name="parameter" /> does not contain <paramref name="item" />.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static ImmutableArray<T> MustContain<T>(
+        this ImmutableArray<T> parameter,
+        T item,
+        Func<ImmutableArray<T>, T, Exception> exceptionFactory
+    )
+    {
+        if (!parameter.Contains(item))
+        {
+            Throw.CustomException(exceptionFactory, parameter, item);
+        }
+
+        return parameter;
+    }
 }