Package org.jsoup.select

Class Elements

java.lang.Object
java.util.AbstractCollection<Element>
java.util.AbstractList<Element>
java.util.ArrayList<Element>
org.jsoup.select.Elements
All Implemented Interfaces:
Serializable, Cloneable, Iterable<Element>, Collection<Element>, List<Element>, RandomAccess, SequencedCollection<Element>
public class Elements extends ArrayList<Element>
A list of Elements, with methods that act on every element in the list.

To get an Elements object, use the Element.select(String) method.

Methods that set, remove, or replace Elements in the list will also act on the underlying DOM.

Author:
Jonathan Hedley, jonathan@hedley.net
See Also:

  • Field Summary

    Fields inherited from class java.util.AbstractList

    modCount

  • Constructor Summary

    Constructors
    Constructor
    Description
    Elements()
     
    Elements(int initialCapacity)
     
    Elements(Collection<Element> elements)
     
    Elements(List<Element> elements)
     
    Elements(Element... elements)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Elements
    addClass(String className)
    Add the class name to every matched element's class attribute.
    Elements
    after(String html)
    Insert the supplied HTML after each matched element's outer HTML.
    Elements
    append(String html)
    Add the supplied HTML to the end of each matched element's inner HTML.
    String
    attr(String attributeKey)
    Get an attribute value from the first matched element that has the attribute.
    Elements
    attr(String attributeKey, String attributeValue)
    Set an attribute on all matched elements.
    Elements
    before(String html)
    Insert the supplied HTML before each matched element's outer HTML.
    void
    clear()
    Removes all the elements from this list, and each of them from the DOM.
    Elements
    clone()
    Creates a deep copy of these elements.
    List<Comment>
    comments()
    Get Comment nodes that are direct child nodes of the selected elements.
    List<DataNode>
    dataNodes()
    Get DataNode nodes that are direct child nodes of the selected elements.
    List<String>
    eachAttr(String attributeKey)
    Get the attribute value for each of the matched elements.
    List<String>
    eachText()
    Get the text content of each of the matched elements.
    Elements
    empty()
    Empty (remove all child nodes from) each matched element.
    Elements
    eq(int index)
    Get the nth matched element as an Elements object.
    Elements
    filter(NodeFilter nodeFilter)
    Perform a depth-first filtering on each of the selected elements.
    @Nullable Element
    first()
    Get the first matched element.
    List<FormElement>
    forms()
    Get the FormElement forms from the selected elements, if any.
    boolean
    hasAttr(String attributeKey)
    Checks if any of the matched elements have this attribute defined.
    boolean
    hasClass(String className)
    Determine if any of the matched elements have this class name set in their class attribute.
    boolean
    hasText()
    Test if any matched Element has any text content, that is not just whitespace.
    String
    html()
    Get the combined inner HTML of all matched elements.
    Elements
    html(String html)
    Set the inner HTML of each matched element.
    boolean
    is(String query)
    Test if any of the matched elements match the supplied query.
    @Nullable Element
    last()
    Get the last matched element.
    Elements
    next()
    Get the immediate next element sibling of each element in this list.
    Elements
    next(String query)
    Get the immediate next element sibling of each element in this list, filtered by the query.
    Elements
    nextAll()
    Get each of the following element siblings of each element in this list.
    Elements
    nextAll(String query)
    Get each of the following element siblings of each element in this list, that match the query.
    Elements
    not(String query)
    Remove elements from this list that match the Selector query.
    String
    outerHtml()
    Get the combined outer HTML of all matched elements.
    Elements
    parents()
    Get all of the parents and ancestor elements of the matched elements.
    Elements
    prepend(String html)
    Add the supplied HTML to the start of each matched element's inner HTML.
    Elements
    prev()
    Get the immediate previous element sibling of each element in this list.
    Elements
    prev(String query)
    Get the immediate previous element sibling of each element in this list, filtered by the query.
    Elements
    prevAll()
    Get each of the previous element siblings of each element in this list.
    Elements
    prevAll(String query)
    Get each of the previous element siblings of each element in this list, that match the query.
    Elements
    remove()
    Remove each matched element from the DOM.
    Element
    remove(int index)
    Remove the Element at the specified index in this ist, and from the DOM.
    boolean
    remove(Object o)
    Remove the specified Element from this list, and from th DOM
    boolean
    removeAll(Collection<?> c)
    Removes from this list, and from the DOM, each of the elements that are contained in the specified collection and are in this list.
    Elements
    removeAttr(String attributeKey)
    Remove an attribute from every matched element.
    Elements
    removeClass(String className)
    Remove the class name from every matched element's class attribute, if present.
    boolean
    removeIf(Predicate<? super Element> filter)
    Remove from the list, and from the DOM, all elements in this list that mach the given filter.
    void
    replaceAll(UnaryOperator<Element> operator)
    Replace each element in this list with the result of the operator, and update the DOM.
    boolean
    retainAll(Collection<?> c)
    Retain in this list, and in the DOM, only the elements that are in the specified collection and are in this list.
    Elements
    select(String query)
    Find matching elements within this element list.
    Element
    set(int index, Element element)
    Replace the Element at the specified index in this list, and in the DOM.
    Elements
    tagName(String tagName)
    Update (rename) the tag name of each matched element.
    String
    text()
    Get the combined text of all the matched elements.
    List<TextNode>
    textNodes()
    Get TextNode nodes that are direct child nodes of the selected elements.
    Elements
    toggleClass(String className)
    Toggle the class name on every matched element's class attribute.
    String
    toString()
    Get the combined outer HTML of all matched elements.
    Elements
    traverse(NodeVisitor nodeVisitor)
    Perform a depth-first traversal on each of the selected elements.
    Elements
    unwrap()
    Removes the matched elements from the DOM, and moves their children up into their parents.
    String
    val()
    Get the form element's value of the first matched element.
    Elements
    val(String value)
    Set the form element's value in each of the matched elements.
    Elements
    wrap(String html)
    Wrap the supplied HTML around each matched elements.

    Methods inherited from class java.util.ArrayList

    add, add, addAll, addAll, addFirst, addLast, contains, ensureCapacity, equals, forEach, get, getFirst, getLast, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, removeFirst, removeLast, removeRange, size, sort, spliterator, subList, toArray, toArray, trimToSize

    Methods inherited from class java.util.AbstractCollection

    containsAll

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.util.Collection

    parallelStream, stream, toArray

    Methods inherited from interface java.util.List

    containsAll, reversed

  • Constructor Details

    • Elements

      public Elements()

    • Elements

      public Elements(int initialCapacity)

    • Elements

      public Elements(Collection<Element> elements)

    • Elements

      public Elements(List<Element> elements)

    • Elements

      public Elements(Element... elements)

  • Method Details

    • clone

      public Elements clone()
      Creates a deep copy of these elements.
      Overrides:
      clone in class ArrayList<Element>
      Returns:
      a deep copy

    • attr

      public String attr(String attributeKey)
      Get an attribute value from the first matched element that has the attribute.
      Parameters:
      attributeKey - The attribute key.
      Returns:
      The attribute value from the first matched element that has the attribute. If no elements were matched (isEmpty() == true), or if the no elements have the attribute, returns empty string.
      See Also:

    • hasAttr

      public boolean hasAttr(String attributeKey)
      Checks if any of the matched elements have this attribute defined.
      Parameters:
      attributeKey - attribute key
      Returns:
      true if any of the elements have the attribute; false if none do.

    • eachAttr

      public List<String> eachAttr(String attributeKey)
      Get the attribute value for each of the matched elements. If an element does not have this attribute, no value is included in the result set for that element.
      Parameters:
      attributeKey - the attribute name to return values for. You can add the abs: prefix to the key to get absolute URLs from relative URLs, e.g.: doc.select("a").eachAttr("abs:href") .
      Returns:
      a list of each element's attribute value for the attribute

    • attr

      public Elements attr(String attributeKey, String attributeValue)
      Set an attribute on all matched elements.
      Parameters:
      attributeKey - attribute key
      attributeValue - attribute value
      Returns:
      this

    • removeAttr

      public Elements removeAttr(String attributeKey)
      Remove an attribute from every matched element.
      Parameters:
      attributeKey - The attribute to remove.
      Returns:
      this (for chaining)

    • addClass

      public Elements addClass(String className)
      Add the class name to every matched element's class attribute.
      Parameters:
      className - class name to add
      Returns:
      this

    • removeClass

      public Elements removeClass(String className)
      Remove the class name from every matched element's class attribute, if present.
      Parameters:
      className - class name to remove
      Returns:
      this

    • toggleClass

      public Elements toggleClass(String className)
      Toggle the class name on every matched element's class attribute.
      Parameters:
      className - class name to add if missing, or remove if present, from every element.
      Returns:
      this

    • hasClass

      public boolean hasClass(String className)
      Determine if any of the matched elements have this class name set in their class attribute.
      Parameters:
      className - class name to check for
      Returns:
      true if any do, false if none do

    • val

      public String val()
      Get the form element's value of the first matched element.
      Returns:
      The form element's value, or empty if not set.
      See Also:

    • val

      public Elements val(String value)
      Set the form element's value in each of the matched elements.
      Parameters:
      value - The value to set into each matched element
      Returns:
      this (for chaining)

    • text

      public String text()
      Get the combined text of all the matched elements.

      Note that it is possible to get repeats if the matched elements contain both parent elements and their own children, as the Element.text() method returns the combined text of a parent and all its children.

      Returns:
      string of all text: unescaped and no HTML.
      See Also:

    • hasText

      public boolean hasText()
      Test if any matched Element has any text content, that is not just whitespace.
      Returns:
      true if any element has non-blank text content.
      See Also:

    • eachText

      public List<String> eachText()
      Get the text content of each of the matched elements. If an element has no text, then it is not included in the result.
      Returns:
      A list of each matched element's text content.
      See Also:

    • html

      public String html()
      Get the combined inner HTML of all matched elements.
      Returns:
      string of all element's inner HTML.
      See Also:

    • outerHtml

      public String outerHtml()
      Get the combined outer HTML of all matched elements.
      Returns:
      string of all element's outer HTML.
      See Also:

    • toString

      public String toString()
      Get the combined outer HTML of all matched elements. Alias of outerHtml().
      Overrides:
      toString in class AbstractCollection<Element>
      Returns:
      string of all element's outer HTML.
      See Also:

    • tagName

      public Elements tagName(String tagName)
      Update (rename) the tag name of each matched element. For example, to change each <i> to a <em>, do doc.select("i").tagName("em");
      Parameters:
      tagName - the new tag name
      Returns:
      this, for chaining
      See Also:

    • html

      public Elements html(String html)
      Set the inner HTML of each matched element.
      Parameters:
      html - HTML to parse and set into each matched element.
      Returns:
      this, for chaining
      See Also:

    • prepend

      public Elements prepend(String html)
      Add the supplied HTML to the start of each matched element's inner HTML.
      Parameters:
      html - HTML to add inside each element, before the existing HTML
      Returns:
      this, for chaining
      See Also:

    • append

      public Elements append(String html)
      Add the supplied HTML to the end of each matched element's inner HTML.
      Parameters:
      html - HTML to add inside each element, after the existing HTML
      Returns:
      this, for chaining
      See Also:

    • before

      public Elements before(String html)
      Insert the supplied HTML before each matched element's outer HTML.
      Parameters:
      html - HTML to insert before each element
      Returns:
      this, for chaining
      See Also:

    • after

      public Elements after(String html)
      Insert the supplied HTML after each matched element's outer HTML.
      Parameters:
      html - HTML to insert after each element
      Returns:
      this, for chaining
      See Also:

    • wrap

      public Elements wrap(String html)
      Wrap the supplied HTML around each matched elements. For example, with HTML <p><b>This</b> is <b>Jsoup</b></p>, doc.select("b").wrap("<i></i>"); becomes <p><i><b>This</b></i> is <i><b>jsoup</b></i></p>
      Parameters:
      html - HTML to wrap around each element, e.g. <div class="head"></div>. Can be arbitrarily deep.
      Returns:
      this (for chaining)
      See Also:

    • unwrap

      public Elements unwrap()
      Removes the matched elements from the DOM, and moves their children up into their parents. This has the effect of dropping the elements but keeping their children.

      This is useful for e.g removing unwanted formatting elements but keeping their contents.

      E.g. with HTML:

      <div><font>One</font> <font><a href="/">Two</a></font></div>

      doc.select("font").unwrap();

      HTML = <div>One <a href="/">Two</a></div>

      Returns:
      this (for chaining)
      See Also:

    • empty

      public Elements empty()
      Empty (remove all child nodes from) each matched element. This is similar to setting the inner HTML of each element to nothing.

      E.g. HTML: <div><p>Hello <b>there</b></p> <p>now</p></div>
      doc.select("p").empty();
      HTML = <div><p></p> <p></p></div>

      Returns:
      this, for chaining
      See Also:

    • remove

      public Elements remove()
      Remove each matched element from the DOM. This is similar to setting the outer HTML of each element to nothing.

      The elements will still be retained in this list, in case further processing of them is desired.

      E.g. HTML: <div><p>Hello</p> <p>there</p> <img /></div>
      doc.select("p").remove();
      HTML = <div> <img /></div>

      Note that this method should not be used to clean user-submitted HTML; rather, use Cleaner to clean HTML.

      Returns:
      this, for chaining
      See Also:

    • select

      public Elements select(String query)
      Find matching elements within this element list.
      Parameters:
      query - A Selector query
      Returns:
      the filtered list of elements, or an empty list if none match.

    • not

      public Elements not(String query)
      Remove elements from this list that match the Selector query.

      E.g. HTML: <div class=logo>One</div> <div>Two</div>
      Elements divs = doc.select("div").not(".logo");
      Result: divs: [<div>Two</div>]

      Parameters:
      query - the selector query whose results should be removed from these elements
      Returns:
      a new elements list that contains only the filtered results

    • eq

      public Elements eq(int index)
      Get the nth matched element as an Elements object.

      See also ArrayList.get(int) to retrieve an Element.

      Parameters:
      index - the (zero-based) index of the element in the list to retain
      Returns:
      Elements containing only the specified element, or, if that element did not exist, an empty list.

    • is

      public boolean is(String query)
      Test if any of the matched elements match the supplied query.
      Parameters:
      query - A selector
      Returns:
      true if at least one element in the list matches the query.

    • next

      public Elements next()
      Get the immediate next element sibling of each element in this list.
      Returns:
      next element siblings.

    • next

      public Elements next(String query)
      Get the immediate next element sibling of each element in this list, filtered by the query.
      Parameters:
      query - CSS query to match siblings against
      Returns:
      next element siblings.

    • nextAll

      public Elements nextAll()
      Get each of the following element siblings of each element in this list.
      Returns:
      all following element siblings.

    • nextAll

      public Elements nextAll(String query)
      Get each of the following element siblings of each element in this list, that match the query.
      Parameters:
      query - CSS query to match siblings against
      Returns:
      all following element siblings.

    • prev

      public Elements prev()
      Get the immediate previous element sibling of each element in this list.
      Returns:
      previous element siblings.

    • prev

      public Elements prev(String query)
      Get the immediate previous element sibling of each element in this list, filtered by the query.
      Parameters:
      query - CSS query to match siblings against
      Returns:
      previous element siblings.

    • prevAll

      public Elements prevAll()
      Get each of the previous element siblings of each element in this list.
      Returns:
      all previous element siblings.

    • prevAll

      public Elements prevAll(String query)
      Get each of the previous element siblings of each element in this list, that match the query.
      Parameters:
      query - CSS query to match siblings against
      Returns:
      all previous element siblings.

    • parents

      public Elements parents()
      Get all of the parents and ancestor elements of the matched elements.
      Returns:
      all of the parents and ancestor elements of the matched elements

    • first

      public @Nullable Element first()
      Get the first matched element.
      Returns:
      The first matched element, or null if contents is empty.

    • last

      public @Nullable Element last()
      Get the last matched element.
      Returns:
      The last matched element, or null if contents is empty.

    • traverse

      public Elements traverse(NodeVisitor nodeVisitor)
      Perform a depth-first traversal on each of the selected elements.
      Parameters:
      nodeVisitor - the visitor callbacks to perform on each node
      Returns:
      this, for chaining

    • filter

      public Elements filter(NodeFilter nodeFilter)
      Perform a depth-first filtering on each of the selected elements.
      Parameters:
      nodeFilter - the filter callbacks to perform on each node
      Returns:
      this, for chaining

    • forms

      public List<FormElement> forms()
      Get the FormElement forms from the selected elements, if any.
      Returns:
      a list of FormElements pulled from the matched elements. The list will be empty if the elements contain no forms.

    • comments

      public List<Comment> comments()
      Get Comment nodes that are direct child nodes of the selected elements.
      Returns:
      Comment nodes, or an empty list if none.

    • textNodes

      public List<TextNode> textNodes()
      Get TextNode nodes that are direct child nodes of the selected elements.
      Returns:
      TextNode nodes, or an empty list if none.

    • dataNodes

      public List<DataNode> dataNodes()
      Get DataNode nodes that are direct child nodes of the selected elements. DataNode nodes contain the content of tags such as script, style etc and are distinct from TextNodes.
      Returns:
      Comment nodes, or an empty list if none.

    • set

      public Element set(int index, Element element)
      Replace the Element at the specified index in this list, and in the DOM.
      Specified by:
      set in interface List<Element>
      Overrides:
      set in class ArrayList<Element>
      Parameters:
      index - index of the element to replace
      element - element to be stored at the specified position
      Returns:
      the old Element at this index
      Since:
      1.17.1

    • remove

      public Element remove(int index)
      Remove the Element at the specified index in this ist, and from the DOM.
      Specified by:
      remove in interface List<Element>
      Overrides:
      remove in class ArrayList<Element>
      Parameters:
      index - the index of the element to be removed
      Returns:
      the old element at this index
      Since:
      1.17.1

    • remove

      public boolean remove(Object o)
      Remove the specified Element from this list, and from th DOM
      Specified by:
      remove in interface Collection<Element>
      Specified by:
      remove in interface List<Element>
      Overrides:
      remove in class ArrayList<Element>
      Parameters:
      o - element to be removed from this list, if present
      Returns:
      if this list contained the Element
      Since:
      1.17.1

    • clear

      public void clear()
      Removes all the elements from this list, and each of them from the DOM.
      Specified by:
      clear in interface Collection<Element>
      Specified by:
      clear in interface List<Element>
      Overrides:
      clear in class ArrayList<Element>
      Since:
      1.17.1
      See Also:

    • removeAll

      public boolean removeAll(Collection<?> c)
      Removes from this list, and from the DOM, each of the elements that are contained in the specified collection and are in this list.
      Specified by:
      removeAll in interface Collection<Element>
      Specified by:
      removeAll in interface List<Element>
      Overrides:
      removeAll in class ArrayList<Element>
      Parameters:
      c - collection containing elements to be removed from this list
      Returns:
      true if elements were removed from this list
      Since:
      1.17.1

    • retainAll

      public boolean retainAll(Collection<?> c)
      Retain in this list, and in the DOM, only the elements that are in the specified collection and are in this list. In other words, remove elements from this list and the DOM any item that is in this list but not in the specified collection.
      Specified by:
      retainAll in interface Collection<Element>
      Specified by:
      retainAll in interface List<Element>
      Overrides:
      retainAll in class ArrayList<Element>
      Parameters:
      c - collection containing elements to be retained in this list
      Returns:
      true if elements were removed from this list
      Since:
      1.17.1

    • removeIf

      public boolean removeIf(Predicate<? super Element> filter)
      Remove from the list, and from the DOM, all elements in this list that mach the given filter.
      Specified by:
      removeIf in interface Collection<Element>
      Overrides:
      removeIf in class ArrayList<Element>
      Parameters:
      filter - a predicate which returns true for elements to be removed
      Returns:
      true if elements were removed from this list
      Since:
      1.17.1

    • replaceAll

      public void replaceAll(UnaryOperator<Element> operator)
      Replace each element in this list with the result of the operator, and update the DOM.
      Specified by:
      replaceAll in interface List<Element>
      Overrides:
      replaceAll in class ArrayList<Element>
      Parameters:
      operator - the operator to apply to each element
      Since:
      1.17.1