zishuo/goquery
1
0
Fork 0
mirror of https://github.com/PuerkitoBio/goquery synced 2025-09-26 21:01:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

Finalize documentation

Browse Source
This commit is contained in:
Martin Angers
2021-06-14 09:06:47 -04:00
parent ee8a7e0a3a
commit b3953ef42a
2 changed files with 26 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
type.go
View File

@@ -124,17 +124,26 @@ type Matcher interface {
// Single compiles a selector string to a Matcher that stops after the first // Single compiles a selector string to a Matcher that stops after the first
// match is found. // match is found.
// //
// By default, Selection.Find and other functions that accept a selector // By default, Selection.Find and other functions that accept a selector string
// string to find nodes will use all matches corresponding to that selector. // to select nodes will use all matches corresponding to that selector. By
// By using the Matcher returned by Single, at most the first match will be // using the Matcher returned by Single, at most the first match will be
// used. // selected.
// //
// Note that the single-selection property of the Matcher only applies for // For example, those two statements are semantically equivalent:
// methods where the Matcher is used to select nodes, not to filter or check //
// if a node matches the Matcher - in those cases, the behaviour of the // sel1 := doc.Find("a").First()
// Matcher is unchanged (e.g. FilterMatcher(Single("div")) will still result // sel2 := doc.FindMatcher(goquery.Single("a"))
// in a Selection with multiple "div"s if there were many "div"s in the //
// Selection to begin with). // The one using Single is optimized to be potentially much faster on large
// documents.
//
// Only the behaviour of the MatchAll method of the Matcher interface is
// altered compared to standard Matchers. This means that the single-selection
// property of the Matcher only applies for Selection methods where the Matcher
// is used to select nodes, not to filter or check if a node matches the
// Matcher - in those cases, the behaviour of the Matcher is unchanged (e.g.
// FilterMatcher(Single("div")) will still result in a Selection with multiple
// "div"s if there were many "div"s in the Selection to begin with).
func Single(selector string) Matcher { func Single(selector string) Matcher {
return singleMatcher{compileMatcher(selector)} return singleMatcher{compileMatcher(selector)}
} }

7
type_test.go
View File

@@ -231,6 +231,13 @@ func TestSingle(t *testing.T) {
t.Fatalf("want %q, got %q", "1", text) t.Fatalf("want %q, got %q", "1", text)
} }
// Verify semantic equivalence
sel1 := doc.Find("div").First()
sel2 := doc.FindMatcher(Single("div"))
if sel1.Text() != sel2.Text() {
t.Fatalf("want sel1 to equal sel2")
}
// Here, the Single has no effect as the selector is used to filter // Here, the Single has no effect as the selector is used to filter
// from the existing selection, not to find nodes in the document. // from the existing selection, not to find nodes in the document.
divs := doc.Find("div") divs := doc.Find("div")