Add selectFirst and expectFirst to Elements

src/main/java/org/jsoup/select/Elements.java

@@ -452,6 +452,32 @@ public Elements select(String query) {
         return Selector.select(query, this);
     }
 
+    /**
+     * Find the first Element that matches the {@link Selector} CSS query within this element list.
+     * <p>This is effectively the same as calling {@code elements.select(query).first()}, but is more efficient as query
+     * execution stops on the first hit.</p>
+     * @param query A {@link Selector} query
+     * @return the first matching element, or <b>{@code null}</b> if there is no match.
+     * @see #expectFirst(String)
+     */
+    public @Nullable Element selectFirst(String query) {
+        return Selector.selectFirst(query, this);
+    }
+
+    /**
+     * Just like {@link #selectFirst(String)}, but if there is no match, throws an {@link IllegalArgumentException}.
+     * @param query A {@link Selector} query
+     * @return the first matching element
+     * @throws IllegalArgumentException if no match is found
+     */
+    public Element expectFirst(String query) {
+        return (Element) Validate.ensureNotNull(
+            Selector.selectFirst(query, this),
+                "No elements matched the query '%s'."
+            , query
+        );
+    }
+
     /**
      * Remove elements from this list that match the {@link Selector} query.
      * <p>

src/main/java/org/jsoup/select/Selector.java

@@ -197,6 +197,28 @@
         return Collector.findFirst(QueryParser.parse(cssQuery), root);
     }
 
+    /**
+     Find the first element matching the query, across multiple roots.
+
+     @param query CSS selector
+     @param roots root elements to descend into
+     @return matching elements, empty if none
+     */
+    public static @Nullable Element selectFirst(String query, Iterable<Element> roots) {
+        Validate.notEmpty(query);
+        Validate.notNull(roots);
+        Evaluator evaluator = QueryParser.parse(query);
+
+        for (Element root : roots) {
+          Element first = Collector.findFirst(evaluator, root);
+          if (first != null) {
+            return first;
+          }
+        }
+
+        return null;
+    }
+
     public static class SelectorParseException extends IllegalStateException {
         public SelectorParseException(String msg) {
             super(msg);

src/test/java/org/jsoup/select/ElementsTest.java

@@ -599,4 +599,37 @@
         // check dom
         assertEquals("<div> One</div><div> Two</div><div> Three</div><div> Four</div>", TextUtil.normalizeSpaces(doc.body().html()));
     }
+
+    @Test public void selectFirst() {
+        Document doc = Jsoup.parse("<p>One</p><p>Two <span>Jsoup</span></p><p><span>Three</span></p>");
+        Element span = doc.children().selectFirst("span");
+        assertNotNull(span);
+        assertEquals("Jsoup", span.text());
+    }
+
+    @Test public void selectFirstNullOnNoMatch() {
+        Document doc = Jsoup.parse("<p>One</p><p>Two</p><p>Three</p>");
+        Element span = doc.children().selectFirst("span");
+        assertNull(span);
+    }
+
+    @Test public void expectFirst() {
+        Document doc = Jsoup.parse("<p>One</p><p>Two <span>Jsoup</span></p><p><span>Three</span></p>");
+        Element span = doc.children().expectFirst("span");
+        assertNotNull(span);
+        assertEquals("Jsoup", span.text());
+    }
+
+    @Test public void expectFirstThrowsOnNoMatch() {
+        Document doc = Jsoup.parse("<p>One</p><p>Two</p><p>Three</p>");
+
+        boolean threw = false;
+        try {
+            Element span = doc.children().expectFirst("span");
+        } catch (IllegalArgumentException e) {
+            threw = true;
+            assertEquals("No elements matched the query 'span'.", e.getMessage());
+        }
+        assertTrue(threw);
+    }
 }