Add ListsMatching, ClassCompositeMatcher

Author: kerrykimbrough

README.md

@@ -100,6 +100,7 @@ can be used to verify the contents of arrays or Iterators.
     * To match an Iterable, use the [`ListsMembers`](http://www.cornutum.org/hamcrest-composites/apidocs/org/cornutum/hamcrest/ListsMembers.html) matcher. 
     * To match an array, use the [`ListsElements`](http://www.cornutum.org/hamcrest-composites/apidocs/org/cornutum/hamcrest/ListsElements.html) matcher. 
     * To match an Iterator, use the [`VisitsList`](http://www.cornutum.org/hamcrest-composites/apidocs/org/cornutum/hamcrest/VisitsList.html) matcher. 
+    * Without using `equals`, use the [`ListsMatching`](http://www.cornutum.org/hamcrest-composites/apidocs/org/cornutum/hamcrest/ListsMatching.html) matcher. 
     * Even if the expected or matched sequence may be `null`? No problem! 
     * And also compare individual members using a composite matcher? No problem! 
 
@@ -114,6 +115,7 @@ For more examples of how to use composite matchers, see the unit tests for:
 * [`ContainsMembers`](src/test/java/org/cornutum/hamcrest/ContainsMembersTest.java)
 * [`ListsElements`](src/test/java/org/cornutum/hamcrest/ListsElementsTest.java)
 * [`ListsMembers`](src/test/java/org/cornutum/hamcrest/ListsMembersTest.java)
+* [`ListsMatching`](src/test/java/org/cornutum/hamcrest/ListsMatchingTest.java)
 * [`MatchesFunction`](src/test/java/org/cornutum/hamcrest/MatchesFunctionTest.java)
 * [`VisitsList`](src/test/java/org/cornutum/hamcrest/VisitsListTest.java)
 * [`VisitsMembers`](src/test/java/org/cornutum/hamcrest/VisitsMembersTest.java)

src/main/java/org/cornutum/hamcrest/BaseCompositeMatcher.java

@@ -37,7 +37,7 @@ public abstract class BaseCompositeMatcher<T> extends BaseMatcher<T>
   private class CompositeMatcher
     {
     private final Object matched;
-    private final Matcher<? super T> mismatch;
+    private Matcher<? super T> mismatch;
 
     /**
      * Creates a new CompositeMatcher instance.
@@ -54,7 +54,7 @@ public CompositeMatcher( Object object)
           ? new IsNull<T>()
           : new IsNot<T>( new IsNull<T>());
         }
-      else
+      else if( (mismatch = getTypeMismatch( object)) == null)
         {
         T actual = (T) object;
         mismatch =
@@ -112,6 +112,16 @@ public void describeMismatch( Object actual, Description description)
     getCompositeMatcher( actual).getMismatch().ifPresent( m -> m.describeMismatch( actual, description));
     }
 
+  /**
+   * If the given object is incompatible with the expected type, returns a Matcher that describes the mismatch.
+   * Otherwise, return null;
+   */
+  protected Matcher<? super T> getTypeMismatch( Object object)
+    {
+    // By default, the expected type is undefined. Successful cast of the given object is assumed.
+    return null;
+    }
+
   /**
    * Adds the Matcher supplied for the expected object to the matchers applied by this Matcher.
    */
@@ -181,6 +191,15 @@ protected static <T,S extends Iterable<T>> ListsMembers.Supplier<T,S> listsMembe
     return new ListsMembers.Supplier<>( memberMatcherSupplier);
     }
 
+  /**
+   * Returns a new {@link ListsMatching.Supplier} that supplies a {@link ListsMatching} matcher using
+   * the given member Matcher supplier.
+   */
+  protected static <T,S extends Iterable<T>> ListsMatching.Supplier<T,S> listsMatching( Function<T,Matcher<T>> memberMatcherSupplier)
+    {
+    return new ListsMatching.Supplier<>( memberMatcherSupplier);
+    }
+
   /**
    * Returns a new {@link ListsElements.Supplier} that supplies a {@link ListsElements} matcher using
    * the given element Matcher supplier.

src/main/java/org/cornutum/hamcrest/ClassCompositeMatcher.java

@@ -0,0 +1,56 @@
+//////////////////////////////////////////////////////////////////////////////
+// 
+//                    Copyright 2020, Cornutum Project
+//                             www.cornutum.org
+//
+//////////////////////////////////////////////////////////////////////////////
+
+package org.cornutum.hamcrest;
+
+import org.hamcrest.Matcher;
+import org.hamcrest.core.IsInstanceOf;
+
+/**
+ * Base class for a composite matcher the verifies the expected type of a matched object.
+ */
+public abstract class ClassCompositeMatcher<T> extends BaseCompositeMatcher<T>
+  {
+  /**
+   * Creates a new ClassCompositeMatcher instance.
+   */
+  protected ClassCompositeMatcher( Class<? extends T> expectedType, T expected)
+    {
+    super( expected);
+    setExpectedType( expectedType);
+    }
+
+  /**
+   * Changes the expected type for this matcher.
+   */
+  protected void setExpectedType( Class<? extends T> expectedType)
+    {
+    this.expectedType = expectedType;
+    }
+
+  /**
+   * Returns the expected type for this matcher.
+   */
+  protected Class<? extends T> getExpectedType()
+    {
+    return expectedType;
+    }
+
+  /**
+   * If the given object is incompatible with the expected type, returns a Matcher that describes the mismatch.
+   * Otherwise, return null;
+   */
+  protected Matcher<? super T> getTypeMismatch( Object object)
+    {
+    return
+      object != null && getExpectedType().isAssignableFrom( object.getClass())
+      ? null
+      : new IsInstanceOf( getExpectedType());
+    }
+
+  private Class<? extends T> expectedType;
+  }

src/main/java/org/cornutum/hamcrest/Composites.java

@@ -374,6 +374,38 @@ public static <T> Matcher<Iterator<T>> visitsList( Function<T,Matcher<T>> member
     return new VisitsList<T>( expected, memberMatcherSupplier);
     }
 
+  /**
+   * Returns a Matcher for an Iterable containing the given sequence of members (in order).
+   * Each member of a matched Iterable must satisfy the Matcher returned 
+   * by the given supplier for its counterpart in the given expected Iterable.
+   */
+  public static <T> Matcher<Iterable<T>> listsMatching( Function<T,Matcher<T>> memberMatcherSupplier, Iterable<? extends T> expected)
+    {
+    return new ListsMatching<T>( expected, memberMatcherSupplier);
+    }
+
+  /**
+   * Returns a Matcher for an Iterable containing the given sequence of members (in order).
+   * Each member of a matched Iterable must satisfy the Matcher returned 
+   * by the given supplier for its counterpart in the given expected Iterable.
+   */
+  @SafeVarargs
+  public static <T> Matcher<Iterable<T>> listsMatching( Function<T,Matcher<T>> memberMatcherSupplier, T... expected)
+    {
+    return listsMatching( memberMatcherSupplier, Arrays.asList( expected));
+    }
+
+  /**
+   * Returns a Matcher for an Iterable containing the given sequence of members (in order).
+   * Each member of a matched Iterable must satisfy the Matcher returned 
+   * by the given supplier for its counterpart in the given expected Iterable.
+   */
+  public static <T> Matcher<Iterable<T>> listsMatching( Function<T,Matcher<T>> memberMatcherSupplier, Iterator<T> expected)
+    {
+    Iterable<T> iterable = () -> expected;
+    return listsMatching( memberMatcherSupplier, iterable);
+    }
+
   /**
    * Returns a Matcher that compares values of the given function, using a result Matcher returned by the given supplier.
    */