net/url: document and add example for ParseQuery("x")

Fixes #16460.

Change-Id: Ie9d5f725d2d7e8210ab6f7604a5a05fc49f707de
Reviewed-on: https://go-review.googlesource.com/31331
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/url/example_test.go b/src/net/url/example_test.go
index 645de2e9092912f8e60a127860d32646ac263d60..4ae772426c8ce404b8c8dae3123277221918d998 100644 (file)
--- a/src/net/url/example_test.go
+++ b/src/net/url/example_test.go
@@ -5,6 +5,7 @@
 package url_test
 
 import (
+       "encoding/json"
        "fmt"
        "log"
        "net/http"
@@ -98,3 +99,21 @@ func ExampleURL_ResolveReference() {
        // Output:
        // http://example.com/search?q=dotnet
 }
+
+func ExampleParseQuery() {
+       m, err := url.ParseQuery(`x=1&y=2&y=3;z`)
+       if err != nil {
+               log.Fatal(err)
+       }
+       fmt.Println(toJSON(m))
+       // Output:
+       // {"x":["1"], "y":["2", "3"], "z":[""]}
+}
+
+func toJSON(m interface{}) string {
+       js, err := json.Marshal(m)
+       if err != nil {
+               log.Fatal(err)
+       }
+       return strings.Replace(string(js), ",", ", ", -1)
+}

diff --git a/src/net/url/url.go b/src/net/url/url.go
index 8824c99ddc09c6cce676518c47c6631f8c759046..2991d3e18edc3dd337b1f8edc42463548a64559a 100644 (file)
--- a/src/net/url/url.go
+++ b/src/net/url/url.go
@@ -777,6 +777,10 @@ func (v Values) Del(key string) {
 // ParseQuery always returns a non-nil map containing all the
 // valid query parameters found; err describes the first decoding error
 // encountered, if any.
+//
+// Query is expected to be a list of key=value settings separated by
+// ampersands or semicolons. A setting without an equals sign is
+// interpreted as a key set to an empty value.
 func ParseQuery(query string) (Values, error) {
        m := make(Values)
        err := parseQuery(m, query)