org.jsoup.select
Class Elements

java.lang.Object
  extended by org.jsoup.select.Elements
All Implemented Interfaces:
Cloneable, Iterable< Element>, Collection< Element>, List< Element>

public class Elements
     
extends Object
implements List< Element>, Cloneable

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.

Author:
Jonathan Hedley, jonathan@hedley.net

Constructor Summary
Elements()
           
Elements(Collection<Element> elements)
           
Elements(Element... elements)
           
Elements(int initialCapacity)
           
Elements(List<Element> elements)
           
 
Method Summary
 boolean add(Element element)
           
 void add(int index, Element element)
           
 boolean addAll(Collection<? extends Element> c)
           
 boolean addAll(int index, Collection<? extends Element> c)
           
 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()
           
 Elements clone()
          Creates a deep copy of these elements.
 boolean contains(Object o)
           
 boolean containsAll(Collection<?> c)
           
 Elements empty()
          Empty (remove all child nodes from) each matched element.
 Elements eq(int index)
          Get the nth matched element as an Elements object.
 boolean equals(Object o)
           
 Element first()
          Get the first matched element.
 List<FormElement> forms()
          Get the FormElement forms from the selected elements, if any.
 Element get(int index)
           
 boolean hasAttr(String attributeKey)
          Checks if any of the matched elements have this attribute set.
 boolean hasClass(String className)
          Determine if any of the matched elements have this class name set in their class attribute.
 int hashCode()
           
 boolean hasText()
           
 String html()
          Get the combined inner HTML of all matched elements.
 Elements html(String html)
          Set the inner HTML of each matched element.
 int indexOf(Object o)
           
 boolean is(String query)
          Test if any of the matched elements match the supplied query.
 boolean isEmpty()
           
 Iterator<Element> iterator()
           
 Element last()
          Get the last matched element.
 int lastIndexOf(Object o)
           
 ListIterator<Element> listIterator()
           
 ListIterator<Element> listIterator(int index)
           
 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 remove()
          Remove each matched element from the DOM.
 Element remove(int index)
           
 boolean remove(Object o)
           
 boolean removeAll(Collection<?> c)
           
 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 retainAll(Collection<?> c)
           
 Elements select(String query)
          Find matching elements within this element list.
 Element set(int index, Element element)
           
 int size()
           
 List<Element> subList(int fromIndex, int toIndex)
           
 Elements tagName(String tagName)
          Update the tag name of each matched element.
 String text()
          Get the combined text of all the matched elements.
 Object[] toArray()
           
<T> T[]
toArray(T[] a)
           
 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.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

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 Detail

clone

public Elements clone()
Creates a deep copy of these elements.

Overrides:
clone in class Object
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(String)

hasAttr

public boolean hasAttr(String attributeKey)
Checks if any of the matched elements have this attribute set.

Parameters:
attributeKey - attribute key
Returns:
true if any of the elements have the attribute; false if none do.

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:
Element.val()

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:
Element.text()

hasText

public boolean hasText()

html

public String html()
Get the combined inner HTML of all matched elements.

Returns:
string of all element's inner HTML.
See Also:
text(), outerHtml()

outerHtml

public String outerHtml()
Get the combined outer HTML of all matched elements.

Returns:
string of all element's outer HTML.
See Also:
text(), html()

toString

public String toString()
Get the combined outer HTML of all matched elements. Alias of outerHtml().

Overrides:
toString in class Object
Returns:
string of all element's outer HTML.
See Also:
text(), html()

tagName

public Elements tagName(String tagName)
Update 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:
Element.tagName(String)

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:
Element.html(String)

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:
Element.prepend(String)

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:
Element.append(String)

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:
Element.before(String)

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:
Element.after(String)

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:
Element.wrap(java.lang.String)

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:
Node.unwrap()

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:
Element.empty(), remove()

remove

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

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:
Element.empty(), empty()

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 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.

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 Element first()
Get the first matched element.

Returns:
The first matched element, or null if contents is empty.

last

public 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

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.

size

public int size()
Specified by:
size in interface Collection<Element>
Specified by:
size in interface List<Element>

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Collection<Element>
Specified by:
isEmpty in interface List<Element>

contains

public boolean contains(Object o)
Specified by:
contains in interface Collection<Element>
Specified by:
contains in interface List<Element>

iterator

public Iterator<Element> iterator()
Specified by:
iterator in interface Iterable<Element>
Specified by:
iterator in interface Collection<Element>
Specified by:
iterator in interface List<Element>

toArray

public Object[] toArray()
Specified by:
toArray in interface Collection<Element>
Specified by:
toArray in interface List<Element>

toArray

public <T> T[] toArray(T[] a)
Specified by:
toArray in interface Collection<Element>
Specified by:
toArray in interface List<Element>

add

public boolean add(Element element)
Specified by:
add in interface Collection<Element>
Specified by:
add in interface List<Element>

remove

public boolean remove(Object o)
Specified by:
remove in interface Collection<Element>
Specified by:
remove in interface List<Element>

containsAll

public boolean containsAll(Collection<?> c)
Specified by:
containsAll in interface Collection<Element>
Specified by:
containsAll in interface List<Element>

addAll

public boolean addAll(Collection<? extends Element> c)
Specified by:
addAll in interface Collection<Element>
Specified by:
addAll in interface List<Element>

addAll

public boolean addAll(int index,
                      Collection<? extends Element> c)
Specified by:
addAll in interface List<Element>

removeAll

public boolean removeAll(Collection<?> c)
Specified by:
removeAll in interface Collection<Element>
Specified by:
removeAll in interface List<Element>

retainAll

public boolean retainAll(Collection<?> c)
Specified by:
retainAll in interface Collection<Element>
Specified by:
retainAll in interface List<Element>

clear

public void clear()
Specified by:
clear in interface Collection<Element>
Specified by:
clear in interface List<Element>

equals

public boolean equals(Object o)
Specified by:
equals in interface Collection<Element>
Specified by:
equals in interface List<Element>
Overrides:
equals in class Object

hashCode

public int hashCode()
Specified by:
hashCode in interface Collection<Element>
Specified by:
hashCode in interface List<Element>
Overrides:
hashCode in class Object

get

public Element get(int index)
Specified by:
get in interface List<Element>

set

public Element set(int index,
                   Element element)
Specified by:
set in interface List<Element>

add

public void add(int index,
                Element element)
Specified by:
add in interface List<Element>

remove

public Element remove(int index)
Specified by:
remove in interface List<Element>

indexOf

public int indexOf(Object o)
Specified by:
indexOf in interface List<Element>

lastIndexOf

public int lastIndexOf(Object o)
Specified by:
lastIndexOf in interface List<Element>

listIterator

public ListIterator<Element> listIterator()
Specified by:
listIterator in interface List<Element>

listIterator

public ListIterator<Element> listIterator(int index)
Specified by:
listIterator in interface List<Element>

subList

public List<Element> subList(int fromIndex,
                             int toIndex)
Specified by:
subList in interface List<Element>


Copyright © 2009-2014 Jonathan Hedley. All Rights Reserved.