Support the same parameter key more than once in Uri query parameters.

sdk/lib/core/uri.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * A parsed URI, such as a URL.
  *
  * **See also:**
@@ skipping 58 matching lines @@
 
   /**
    * Cache the computed return value of [pathSegements].
    */
   List<String> _pathSegments;
 
   /**
    * Cache the computed return value of [queryParameters].
    */
   Map<String, String> _queryParameters;
+  Map<String, List<String>> _queryParameterLists;
 
   /// Internal non-verifying constructor. Only call with validated arguments.
   Uri._internal(this.scheme,
                 this._userInfo,
                 this._host,
                 this._port,
                 this._path,
                 this._query,
                 this._fragment);
 
@@ skipping 40 matching lines @@
    * list of characters: `!$&'()*+,;=:@`. If the other components
    * calls for an absolute path a leading slash `/` is prepended if
    * not already there.
    *
    * The query component is set through either [query] or
    * [queryParameters]. When [query] is used the provided string should
    * be a valid URI query, but invalid characters other than general delimiters,
    * will be escaped if necessary.
    * When [queryParameters] is used the query is built from the
    * provided map. Each key and value in the map is percent-encoded
-   * and joined using equal and ampersand characters. The
-   * percent-encoding of the keys and values encodes all characters
-   * except for the unreserved characters.
+   * and joined using equal and ampersand characters.
+   * A value in the map must be either a string, or a an [Iterable] of strings,
+   * where the latter corresponds to multiple values for the same key.
+   * The percent-encoding of the keys and values encodes all characters
+   * except for the unreserved characters, and replaces spaces with `+`.

[floitsch, 2016/01/12 16:51:33]

Consider breaking it into paragraphs.

Use http://spec.commonmark.org/dingus/ for an approximate look at the current
output.

[Lasse Reichstein Nielsen, 2016/01/13 12:30:14]

More paragraphs added.

    * If `query` is the empty string, it is equivalent to omitting it.
    * To have an actual empty query part,
    * use an empty list for `queryParameters`.
-   * If both `query` and `queryParameters` are omitted or `null`, the
-   * URI will have no query part.
+   * If both `query` and `queryParameters` are omitted or `null`,
+   * the URI will have no query part.

[floitsch, 2016/01/12 16:51:33]

has no

[Lasse Reichstein Nielsen, 2016/01/13 12:30:14]

Changed here, and in other places in the file.

    *
    * The fragment component is set through [fragment].
    * It should be a valid URI fragment, but invalid characters other than
    * general delimiters, will be escaped if necessary.
    * If `fragment` is omitted or `null`, the URI will have no fragment part.
    */
   factory Uri({String scheme : "",
                String userInfo : "",
                String host,
                int port,
                String path,
                Iterable<String> pathSegments,
                String query,
-               Map<String, String> queryParameters,
+               Map<String, dynamic> queryParameters,
                String fragment}) {
     scheme = _makeScheme(scheme, 0, _stringOrNullLength(scheme));
     userInfo = _makeUserInfo(userInfo, 0, _stringOrNullLength(userInfo));
     host = _makeHost(host, 0, _stringOrNullLength(host), false);
     // Special case this constructor for backwards compatibility.
     if (query == "") query = null;
     query = _makeQuery(query, 0, _stringOrNullLength(query), queryParameters);
     fragment = _makeFragment(fragment, 0, _stringOrNullLength(fragment));
     port = _makePort(port, scheme);
     bool isFile = (scheme == "file");
@@ skipping 926 matching lines @@
         : new List<String>.unmodifiable(
               pathToSplit.split("/").map(Uri.decodeComponent));
     _pathSegments = result;
     return result;
   }
 
   /**
    * Returns the URI query split into a map according to the rules
    * specified for FORM post in the [HTML 4.01 specification section
    * 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
+   * Each key and value in the returned map has been decoded.
+   * If there is no query the empty map is returned.
+   *
+   * Keys in the query string that have no value are mapped to the
+   * empty string.
+   * If a key occurs more than once in the query string, it is mapped to
+   * one of the values. The [queryParametersAll] getter can provide a

[floitsch, 2016/01/12 16:51:33]

which one?
Either explicitly state a "random" one, or state which one it is.

[Lasse Reichstein Nielsen, 2016/01/13 12:30:14]

Now say "arbitrary".

+   * map that maps to all the values.
+   *
+   * The returned map is unmodifiable.
+   */
+  Map<String, String> get queryParameters {
+    if (_queryParameters == null) {
+      _queryParameters =
+          new UnmodifiableMapView<String, String>(splitQueryString(query));
+    }
+    return _queryParameters;
+  }
+
+  /**
+   * Returns the URI query split into a map according to the rules
+   * specified for FORM post in the [HTML 4.01 specification section
+   * 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").

[floitsch, 2016/01/12 16:51:33]

make sure that this encodes correctly with dartdoc.

[Lasse Reichstein Nielsen, 2016/01/13 12:30:14]

Checks out correctly in the commonmark checker linked above.

    * Each key and value in the returned map has been decoded. If there is no
    * query the empty map is returned.
    *
-   * Keys in the query string that have no value are mapped to the
-   * empty string.
+   * Keys are mapped to lists of their values. If a key occurs only once,
+   * its value is a singleton list. If a key occurs with no value, the
+   * empty string is used as the value for that occurrence.
    *
-   * The returned map is unmodifiable and will throw [UnsupportedError] on any
-   * calls that would mutate it.
+   * The returned map and the lists it contains are unmodifiable.
    */
-  Map<String, String> get queryParameters {
-    if (_queryParameters == null) {
-      _queryParameters = new UnmodifiableMapView(splitQueryString(query));
+  Map<String, List<String>> get queryParametersAll {
+    if (_queryParameterLists == null) {
+      Map queryParameterLists = _splitQueryStringAll(query);
+      for (var key in queryParameterLists.keys) {
+        queryParameterLists[key] =
+            new List<String>.unmodifiable(queryParameterLists[key]);
+      }
+      _queryParameterLists =
+          new Map<String, List<String>>.unmodifiable(queryParameterLists);
     }
-    return _queryParameters;
+    return _queryParameterLists;
   }
 
   /**
    * Returns a URI where the path has been normalized.
    *
    * A normalized path does not contain `.` segments or non-leading `..`
    * segments.
    * Only a relative path with no scheme or authority may contain
    * leading `..` segments,
    * a path that starts with `/` will also drop any leading `..` segments.
@@ skipping 206 matching lines @@
 
   static String _makeQuery(String query, int start, int end,
                            Map<String, String> queryParameters) {
     if (query == null && queryParameters == null) return null;
     if (query != null && queryParameters != null) {
       throw new ArgumentError('Both query and queryParameters specified');
     }
     if (query != null) return _normalize(query, start, end, _queryCharTable);
 
     var result = new StringBuffer();
-    var first = true;
-    queryParameters.forEach((key, value) {
-      if (!first) {
-        result.write("&");
-      }
-      first = false;
+    var separator = "";
+
+    void writeParameter(String key, String value) {
+      result.write(separator);
+      separator = "&";
       result.write(Uri.encodeQueryComponent(key));
-      if (value != null && !value.isEmpty) {
+      if (value != null && value.isNotEmpty) {
         result.write("=");
         result.write(Uri.encodeQueryComponent(value));
       }
+    }
+
+    queryParameters.forEach((key, value) {
+      if (value == null || value is String) {
+        writeParameter(key, value);
+      } else {
+        Iterable values = value;
+        for (String value in values) {
+          writeParameter(key, value);
+        }
+      }
     });
     return result.toString();
   }
 
   static String _makeFragment(String fragment, int start, int end) {
     if (fragment == null) return null;
     return _normalize(fragment, start, end, _queryCharTable);
   }
 
   static int _stringOrNullLength(String s) => (s == null) ? 0 : s.length;
@@ skipping 781 matching lines @@
       } else if (index != 0) {
         var key = element.substring(0, index);
         var value = element.substring(index + 1);
         map[Uri.decodeQueryComponent(key, encoding: encoding)] =
             decodeQueryComponent(value, encoding: encoding);
       }
       return map;
     });
   }
 
+  static List _createList() => [];
+
+  static Map _splitQueryStringAll(
+      String query, {Encoding encoding: UTF8}) {
+    Map result = {};
+    int i = 0;
+    int start = 0;
+    int equalsIndex = -1;
+
+    void parsePair(int start, int equalsIndex, int end) {
+      String key;
+      String value;
+      if (start == end) return;
+      if (equalsIndex < 0) {
+        key =  _uriDecode(query, start, end, encoding, true);
+        value = "";
+      } else {
+        key = _uriDecode(query, start, equalsIndex, encoding, true);
+        value = _uriDecode(query, equalsIndex + 1, end, encoding, true);
+      }
+      result.putIfAbsent(key, _createList).add(value);
+    }
+
+    const int _equals = 0x3d;
+    const int _ampersand = 0x26;
+    while (i < query.length) {
+      int char = query.codeUnitAt(i);
+      if (char == _equals) {
+        if (equalsIndex < 0) equalsIndex = i;
+      } else if (char == _ampersand) {
+        parsePair(start, equalsIndex, i);
+        start = i + 1;
+        equalsIndex = -1;
+      }
+      i++;
+    }
+    parsePair(start, equalsIndex, i);
+    return result;
+  }
+
   /**
    * Parse the [host] as an IP version 4 (IPv4) address, returning the address
    * as a list of 4 bytes in network byte order (big endian).
    *
    * Throws a [FormatException] if [host] is not a valid IPv4 address
    * representation.
    */
   static List<int> parseIPv4Address(String host) {
     void error(String msg) {
       throw new FormatException('Illegal IPv4 address, $msg');
@@ skipping 1088 matching lines @@
   // All non-escape RFC-2396 uric characters.
   //
   //  uric        =  reserved | unreserved | escaped
   //  reserved    =  ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | ","
   //  unreserved  =  alphanum | mark
   //  mark        =  "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
   //
   // This is the same characters as in a URI query (which is URI pchar plus '?')
   static const _uricTable = Uri._queryCharTable;
 }