Add Uri.replace which creates a new Uri with the same fields as the original, but with some fields …

sdk/lib/core/uri.dart

Index: sdk/lib/core/uri.dart
diff --git a/sdk/lib/core/uri.dart b/sdk/lib/core/uri.dart
index 73a97d80e1c3288aac66beca9735b5bf3d59c4c8..5d2a7b4a40838f6760c48c6f28096aff8ebc6f48 100644
--- a/sdk/lib/core/uri.dart
+++ b/sdk/lib/core/uri.dart
@@ -786,6 +786,99 @@ class Uri {
   }
 
   /**
+   * Returns a new `Uri` based on this one, but with some parts replaced.
+   *
+   * This method takes the same parameters as the [new Uri] constructor,
+   * and they are handled in the same way.
+   *
+   * At most one of [path] and [pathSegments] must be provided.
+   * Likewise, at most one of [query] and [queryParameters] must be provided.
+   *
+   * Each part that is not provided will take its value from this `Uri` instead.
+   *
+   * This is different from [Uri.resolve] which overrides in a hierarchial
+   * manner. This method can replace any part
+   *
+   * Example:
+   *
+   *     Uri uri1 = Uri.parse("a://b@c:4/d/e?f#g");
+   *     Uri uri2 = uri1.replace(scheme: "A", path: "D/E/E", fragment: "G");
+   *     print(uri2);  // prints "A://b@c:4/D/E/E/?f#G"
+   *
+   * Using this method is similar to using the `new Uri` constructor with

[Anders Johnsen, 2014/07/29 07:13:33]

This is the second paragraph mentioning it's similar to `new Uri`.

[Lasse Reichstein Nielsen, 2014/08/05 10:30:39]

I think it's ok. It really is similar.
I've slightly rewritten the documentation.

+   * some of the arguments taken from this `Uri` . Example:
+   *
+   *     Uri uri3 = new Uri(
+   *         scheme: "A",
+   *         userInfo: uri1.userInfo,
+   *         host: uri1.host,
+   *         port: uri1.port,
+   *         path: "D/E/E",
+   *         query: uri1.query,
+   *         fragment: "G");
+   *     print(uri3);  // prints "A://b@c:4/D/E/E/?f#G"
+   *     print(uri2 == uri3);  // prints true.
+   *
+   * Using this method may be slightly faster than calling the [new Uri]
+   * constructor as above, because the parts take from this `Uri` do not
+   * need to be checked for validity again.
+   */
+  Uri replace({String scheme,

[floitsch, 2014/06/24 09:15:53]

I don't like "replace" it gives the impression that it manipulates the receiver.

maybe "with" or "withReplaced" or "toUriWith" or "toUri" ?

[Lasse Reichstein Nielsen, 2014/06/24 09:25:58]

I picked "replace" because we already use it in the same sense on String.
"with" is a keyword, otherwise it would be my preferred alternative.

I don't like the other suggestions. Too long without actually being better, but
I would be open to another, still simple and telling, name.

[floitsch, 2014/06/24 09:32:27]

Could we push to make `with` a pseudo-keyword?
But true: we use a similar name on String, too.

[kustermann, 2014/06/25 00:54:38]

The Uri class is only one example. I've argued with kevmoo that it is nearly
always beneficial to have copy-on-write functions on immutable data types (out
of this discussion he filed the bug).

The shelf package has now immutable (http) Request/Response classes and they use
the name "change()". I have no strong preferences here, but we should be
consistent I think.

It may also be worthwhile to mention that it is not possible to set a field to
"null" when it was non-null before using this method.

[Lasse Reichstein Nielsen, 2014/06/26 06:01:31]

I like "change" even less than "replace", when it comes to not sounding like it
changes the object. Another alternative is "update", with all the same
weaknesses. I'd go for replace, for consistency with String, if not for anything
else.

Another alternative is "where", but we already used that for a completely
different thing. Sadly "with" is taken as a keyword.

Now, if we allowed arbitrary parameters to operator[], we could do:
  var uri2 = uri[path: "/asafss/", query: "nix"];
THAT would be neat.
We could use "call" to make it callable and do:
  var uri2 = uri(path: "/asafss/", query: "nix");
Not as good, though, and probably very confusing to read.


Good point on the inability to replace something with nothing. You'll have to
use the Uri constructor manually in that case.

[Anders Johnsen, 2014/06/26 08:20:35]

What about

  Uri.from(Uri uri, {...});

?

[kustermann, 2014/06/27 20:45:05]

It's longer, not nice and will be special for Uri. I would rather like have a
very nice mechanism of changing immutable data types in a copy-on-write fashion.

[kustermann, 2014/06/27 20:45:05]

Why do you have so many concerns about replace/change/... ? It is really
replacing/changing something, right? It's not replacing it in-place but rather
makes first a copy. I think this is fine. If we make the pattern consistent,
people will easily get it.

Have you ever heard a single complaint about "String.replace()" ?
I did not.

On 2014/06/26 06:01:31, Lasse Reichstein Nielsen wrote:

+               String userInfo,
+               String host,
+               int port,
+               String path,
+               Iterable<String> pathSegments,
+               String query,
+               Map<String, String> queryParameters,
+               String fragment}) {
+    if (scheme == null) {
+      scheme = this.scheme;
+    } else {
+      scheme = _makeScheme(scheme, scheme.length);
+    }
+    if (userInfo == null) {
+      userInfo = this.userInfo;
+    } else {
+      userInfo = _makeUserInfo(userInfo, 0, userInfo.length);
+    }
+    if (host == null) {
+      host = this.host;
+    } else {
+      host = _makeHost(host, 0, host.length, false);
+    }
+    if (port == null) {
+      port = this.port;
+    }
+
+    bool ensureLeadingSlash = (host != "" || scheme == "file");
+    if (path == null && pathSegments == null) {
+      path = this.path;
+      if (ensureLeadingSlash && !path.isEmpty && !path.startsWith('/')) {
+        path = "/$path";
+      }
+    } else {
+      path = _makePath(path, 0, _stringOrNullLength(path), pathSegments,
+                       ensureLeadingSlash);
+    }
+
+    if (query == null && queryParameters == null) {
+      query = this.query;
+    } else {
+      query = _makeQuery(query, 0, _stringOrNullLength(query), queryParameters);
+    }
+
+    if (fragment == null) {
+      fragment = this.fragment;
+    } else {
+      fragment = _makeFragment(fragment, 0, fragment.length);
+    }
+
+    return new Uri._internal(
+        scheme, userInfo, host, port, path, query, fragment);
+  }
+
+  /**
    * Returns the URI path split into its segments. Each of the
    * segments in the returned list have been decoded. If the path is
    * empty the empty list will be returned. A leading slash `/` does