Struct Selection 

pub struct Selection<'a> { /* private fields */ }

Selection represents a collection of nodes matching some criteria. The initial Selection object can be created by using Document::select, and then manipulated using methods itself.

Implementations

impl Selection<'_>

pub fn attr(&self, name: &str) -> Option<Tendril<UTF8>>

Gets the specified attribute’s value for the first element in the selection. To get the value for each element individually, use a looping construct such as map method.

pub fn attrs(&self) -> Vec<Attribute>

Gets all attributes` values for the first element in the selection. To get the value for each element individually, use a looping construct such as map method.

pub fn has_attr(&self, name: &str) -> bool

Checks if the first element in the selection has an attribute with the name.

pub fn attr_or(&self, name: &str, default: &str) -> Tendril<UTF8>

Works like attr but returns default value if attribute is not present.

pub fn set_attr(&self, name: &str, val: &str)

Sets the given attribute to each element in the set of matched elements.

pub fn remove_attr(&self, name: &str)

Removes the named attribute from each element in the set of matched elements.

pub fn remove_attrs(&self, names: &[&str])

Removes named attributes from each element in the set of matched elements.

Arguments

• names - A list of attribute names to remove. Empty slice removes no attributes.

pub fn retain_attrs(&self, names: &[&str])

Retains only the attributes with the specified names from each element in the set of matched elements.

Arguments

• names - A list of attribute names to retain. Empty slice retains no attributes.

pub fn remove_all_attrs(&self)

Removes all attributes from each element in the set of matched elements.

pub fn rename(&self, name: &str)

Renames tag of each element in the set of matched elements.

pub fn strip_elements(&self, names: &[&str])

Removes matching elements from the descendants, but keeps their children (if any) in the tree.

Unlike Self::remove, this method only deletes the elements themselves, promoting their children to the parent level, thus preserving the nested structure of the remaining nodes.

Arguments

• names - A list of element names to strip.

pub fn id(&self) -> Option<Tendril<UTF8>>

Returns the id of the first element in the set of matched elements.

pub fn class(&self) -> Option<Tendril<UTF8>>

Returns the class name of the first element in the set of matched elements.

pub fn add_class(&self, class: &str)

Adds the given class to each element in the set of matched elements. Multiple class names can be specified, separated by a space via multiple arguments.

pub fn has_class(&self, class: &str) -> bool

Determines whether any of the matched elements are assigned the given class.

pub fn remove_class(&self, class: &str)

Removes the given class from each element in the set of matched elements. Multiple class names can be specified, separated by a space via multiple arguments.

pub fn length(&self) -> usize

Returns the number of elements in the selection object.

pub fn size(&self) -> usize

Is an alias for length.

pub fn exists(&self) -> bool

Is there any matched elements.

pub fn is_empty(&self) -> bool

pub fn html(&self) -> Tendril<UTF8>

Gets the HTML contents of the first element in the set of matched elements. It includes the first matching element and its children nodes.

pub fn inner_html(&self) -> Tendril<UTF8>

Gets the HTML contents of the first element in the set of matched elements. It includes only children nodes.

pub fn try_html(&self) -> Option<Tendril<UTF8>>

Gets the HTML contents of the first element in the set of matched elements. It includes the first matching element and its children nodes.

pub fn try_inner_html(&self) -> Option<Tendril<UTF8>>

Gets the HTML contents of the first element in the set of matched elements. It includes only children nodes.

pub fn text(&self) -> Tendril<UTF8>

Gets the combined text content of each element in the set of matched elements, including their descendants.

pub fn immediate_text(&self) -> Tendril<UTF8>

Gets the combined text content of each element in the set of matched, without their descendants.

pub fn formatted_text(&self) -> Tendril<UTF8>

Returns the formatted text of the selected nodes and their descendants. This is the same as the text() method, but with a few differences:

• Whitespace is normalized so that there is only one space between words.
• All whitespace is removed from the beginning and end of the text.
• After block elements, a double newline is added.
• For elements like br, ‘hr’, ‘li’, ‘tr’ a single newline is added.

impl<'a> Selection<'a>

pub fn is(&self, sel: &str) -> bool

Checks the current matched set of elements against a selector and returns true if at least one of these elements matches.

pub fn is_matcher(&self, matcher: &Matcher) -> bool

Checks the current matched set of elements against a matcher and returns true if at least one of these elements matches.

pub fn is_selection(&self, other: &Selection<'_>) -> bool

Checks the current matches set of elements against a selection and returns true if at least one of these elements matches.

pub fn filter(&self, sel: &str) -> Selection<'a>

Filters the current set of matched elements to those that match the given CSS selector.

Panics

Arguments

• sel - The CSS selector to match against.

Returns

A new Selection object containing the matched elements.

pub fn try_filter(&self, sel: &str) -> Option<Selection<'a>>

Reduces the current set of matched elements to those that match the given CSS selector.

Arguments

• sel - The CSS selector to match against.

Returns

None if the selector was invalid, otherwise a new Selection object containing the matched elements.

pub fn filter_matcher(&self, matcher: &Matcher) -> Selection<'a>

Reduces the current set of matched elements to those that match the given matcher.

Arguments

• matcher - The matcher to match against.

Returns

A new Selection object containing the matched elements.

pub fn filter_selection(&self, other: &Selection<'_>) -> Selection<'a>

Reduces the set of matched elements to those that match a node in the specified Selection. It returns a new Selection for this subset of elements.

pub fn add(&self, sel: &str) -> Selection<'a>

Adds nodes that match the given CSS selector to the current selection.

Panics

If matcher contains invalid CSS selector it panics.

Arguments

• sel - The CSS selector to match against.

Returns

The new Selection containing the original nodes and the new nodes.

pub fn try_add(&self, sel: &str) -> Option<Selection<'_>>

Adds nodes that match the given CSS selector to the current selection.

If matcher contains invalid CSS selector it returns None.

Arguments

• sel - The CSS selector to match against.

Returns

The new Selection containing the original nodes and the new nodes.

pub fn add_matcher(&self, matcher: &Matcher) -> Selection<'a>

Adds nodes that match the given matcher to the current selection.

Arguments

• matcher - The matcher to match against.

Returns

The new Selection containing the original nodes and the new nodes.

pub fn add_selection(&self, other: &'a Selection<'_>) -> Selection<'a>

Adds a selection to the current selection.

Behaves like Union for sets.

Arguments

• other - The selection to add to the current selection.

Returns

A new Selection object containing the combined elements.

impl Selection<'_>

pub fn remove(&self)

Removes the set of matched elements from the document.

pub fn replace_with_selection(&self, sel: &Selection<'_>)

Replaces each element in the set of matched element with the nodes from the given selection.

This follows the same rules as append.

Note: goquery’s behavior is taken as the basis.

pub fn append_selection(&self, sel: &Selection<'_>)

Appends the elements in the selection to the end of each element in the set of matched elements. Note: goquery’s behavior is taken as the basis.

pub fn prepend_selection(&self, sel: &Selection<'_>)

Prepends the elements in the selection to the beginning of each element in the set of matched elements. Note: goquery’s behavior is taken as the basis.

pub fn set_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Set the html contents of each element in the selection to specified parsed HTML.

pub fn replace_with_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Replaces each element in the set of matched elements with the parsed HTML.

This follows the same rules as append.

pub fn append_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Parses the html and appends it to the set of matched elements.

pub fn prepend_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Parses the html and prepends it to the set of matched elements.

pub fn before_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Parses the html and inserts it before the set of matched elements.

pub fn after_html<T>(&self, html: T)

where T: Into<Tendril<UTF8>>,

Parses the html and inserts it after the set of matched elements.

pub fn set_text(&self, text: &str)

Sets the content of each element in the selection to specified content. Doesn’t escapes the text.

If simple text needs to be inserted, this method is preferable to Selection::set_html, because it is more lightweight – it does not create a fragment tree underneath.

impl<'a> Selection<'a>

pub fn select<'b>(&self, sel: &'b str) -> Selection<'a>

where 'a: 'b,

Gets the descendants of each element in the current set of matched elements, filter by a selector. It returns a new Selection object containing these matched elements.

Panics

Panics if failed to parse the given CSS selector.

pub fn select_matcher(&self, matcher: &Matcher) -> Selection<'a>

Gets the descendants of each element in the current set of matched elements, filter by a matcher. It returns a new Selection object containing these matched elements.

pub fn nip(&self, sel: &'a str) -> Selection<'a>

Alias for select, it gets the descendants of each element in the current set of matched elements, filter by a selector. It returns a new Selection object containing these matched elements.

Panics

Panics if failed to parse the given CSS selector.

pub fn try_select(&self, sel: &str) -> Option<Selection<'a>>

Gets the descendants of each element in the current set of matched elements, filter by a selector. It returns a new Selection object containing these matched elements.

pub fn select_single_matcher(&self, matcher: &Matcher) -> Selection<'a>

Gets the descendants of each element in the current set of matched elements, filter by a matcher. It returns a new Selection object containing elements of the single (first) match..

pub fn select_single(&self, sel: &str) -> Selection<'a>

Gets the descendants of each element in the current set of matched elements, filter by a selector. It returns a new selection object containing elements of the single (first) match.

Panics

Panics if failed to parse the given CSS selector.

pub fn nodes(&self) -> &[NodeRef<'a>]

Returns a slice of underlying nodes.

pub fn iter(&self) -> Selections<NodeRef<'a>>

Creates an iterator over these matched elements.

pub fn parent(&self) -> Selection<'a>

Gets the parent of each element in the selection. It returns a mew Selection object containing these elements.

pub fn children(&self) -> Selection<'a>

Gets the child elements of each element in the selection. It returns a new Selection object containing these elements.

pub fn ancestors(&self, max_depth: Option<usize>) -> Selection<'a>

Gets the ancestor elements of each element in the selection.

Arguments

• max_depth - The maximum depth of the ancestors to retrieve.

Returns

A new Selection object containing these elements.

pub fn next_sibling(&self) -> Selection<'a>

Gets the immediately following sibling of each element in the selection. It returns a new Selection object containing these elements.

pub fn prev_sibling(&self) -> Selection<'a>

Gets the immediately previous sibling of each element in the selection. It returns a new Selection object containing these elements.

pub fn first(&self) -> Selection<'a>

Reduces the set of matched elements to the first in the set. It returns a new selection object, and an empty selection object if the selection is empty.

pub fn last(&self) -> Selection<'a>

Reduces the set of matched elements to the last in the set. It returns a new selection object, and an empty selection object if the selection is empty.

pub fn get(&self, index: usize) -> Option<&NodeRef<'a>>

Retrieves the underlying node at the specified index.

impl Selection<'_>

This impl block contains no public items.

internal methods

impl<'a> Selection<'a>

pub fn select_matcher_iter<'b>( &self, matcher: &'b Matcher, ) -> Box<dyn Iterator<Item = NodeRef<'a>> + 'b>

where 'a: 'b,

Iterates over all nodes that match the given matcher. Useful for read-only operations.

If elements assumed to be changed during iteration, use Selection::select_matcher instead or it will panic with std::cell::BorrowMutError.

Trait Implementations

impl<'a> Clone for Selection<'a>

fn clone(&self) -> Selection<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Selection<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> Default for Selection<'a>

fn default() -> Selection<'a>

Returns the “default value” for a type.

impl<'a> From<NodeRef<'a>> for Selection<'a>

fn from(node: NodeRef<'a>) -> Selection<'a>

Converts to this type from the input type.

impl<'a> From<Vec<NodeRef<'a>>> for Selection<'a>

fn from(nodes: Vec<NodeRef<'a>>) -> Selection<'a>

Converts to this type from the input type.