Added Elements.deselect and Elements.asList

Methods to allow modification of the contents of the list without modifying the DOM.

Fixes #2100

Author: jhy

CHANGES.md

@@ -8,6 +8,9 @@
 
 * `Element.cssSelector()` will prefer to return shorter selectors by using ancestor IDs when available and unique. E.g.
   `#id > div > p` instead of  `html > body > div > div > p` [#2283](https://github.com/jhy/jsoup/pull/2283).
+* Added `Elements.deselect(int index)` and `Elements.deselect(Object o)` methods to remove elements from the `Elements`
+  list without affecting the DOM. And added `Elements.asList()` method to get a modifiable list of elements without
+  affecting the DOM. (Each Element is still connected to the DOM.) [#2100](https://github.com/jhy/jsoup/issues/2100).
 
 ### Bug Fixes
 

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

@@ -59,6 +59,20 @@ public Elements clone() {
         return clone;
     }
 
+    /**
+     Convenience method to get the Elements as a plain ArrayList. This allows modification to the list of elements
+     without modifying the source Document. I.e. whereas calling {@code elements.remove(0)} will remove the element from
+     both the Elements and the DOM, {@code elements.asList().remove(0)} will remove the element from the list only.
+     <p>Each Element is still the same DOM connected Element.</p>
+
+     @return a new ArrayList containing the elements in this list
+     @since 1.19.2
+     @see #Elements(List)
+     */
+    public ArrayList<Element> asList() {
+        return new ArrayList<>(this);
+    }
+
     // attribute methods
     /**
      Get an attribute value from the first matched element that has the attribute.
@@ -729,7 +743,7 @@ private <T extends Node> List<T> childNodesOfType(Class<T> tClass) {
     }
 
     /**
-     Remove the specified Element from this list, and from th DOM
+     Remove the specified Element from this list, and from the DOM.
      * @param o element to be removed from this list, if present
      * @return if this list contained the Element
      * @since 1.17.1
@@ -744,6 +758,26 @@ private <T extends Node> List<T> childNodesOfType(Class<T> tClass) {
         }
     }
 
+    /**
+     * Remove the Element at the specified index in this list, but not from the DOM.
+     * @param index the index of the element to be removed
+     * @return the old element at this index
+     * @since 1.19.2
+     */
+    public Element deselect(int index) {
+        return super.remove(index);
+    }
+
+    /**
+     * Remove the specified Element from this list, but not from the DOM.
+     * @param o element to be removed from this list, if present
+     * @return if this list contained the Element
+     * @since 1.19.2
+     */
+    public boolean deselect(Object o) {
+        return super.remove(o);
+    }
+
     /**
      Removes all the elements from this list, and each of them from the DOM.
      * @since 1.17.1

src/test/java/org/jsoup/nodes/ElementTest.java

@@ -3061,4 +3061,40 @@ public void invalidCharactersDiscardedInXml() {
         assertFalse(cleaned.contains("\uFFFF"));
         assertTrue(cleaned.matches("AAA *BBB *CCC *DDD"));
     }
+
+    @Test
+    public void asList() {
+        // supports https://github.com/jhy/jsoup/issues/2100
+        Document doc = Jsoup.parse("<p id=1>One</p><p>Two</p><p>Three</p>");
+        Elements els = doc.select("p");
+        ArrayList<Element> list = els.asList();
+        assertEquals(els.size(), list.size());
+
+        // does not modify backing DOM
+        list.remove(0);
+        assertEquals(3, els.size());
+        assertEquals(2, list.size());
+
+        Element el = doc.expectFirst("#1");
+        assertSame(doc, el.ownerDocument());
+    }
+
+    @Test
+    public void deselect() {
+        // supports https://github.com/jhy/jsoup/issues/2100
+        Document doc = Jsoup.parse("<div><p>One</p><p>Two</p><p>Three</p></div>");
+        Elements els = doc.select("p");
+        Element parent = doc.expectFirst("div");
+
+        Element removedByIndex = els.deselect(1);
+        assertEquals("Two", removedByIndex.text());
+        assertEquals(2, els.size());
+        assertEquals(3, parent.childrenSize());
+
+        Element toRemove = doc.expectFirst("p:contains(Three)");
+        boolean removedByObject = els.deselect(toRemove);
+        assertTrue(removedByObject);
+        assertEquals(1, els.size());
+        assertEquals(3, parent.childrenSize());
+    }
 }