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

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 768 matching lines @@
       }
     } else {
       // Relative URI.
       var pathSegments = path.split(sep);
       _checkWindowsPathReservedCharacters(pathSegments, true);
       return new Uri(pathSegments: pathSegments);
     }
   }
 
   /**
+   * 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
    * not affect the segments returned.
    *
    * The returned list is unmodifiable and will throw [UnsupportedError] on any
    * calls that would mutate it.
    */
   List<String> get pathSegments {
     if (_pathSegments == null) {
@@ skipping 1396 matching lines @@
       0xafff,   // 0x30 - 0x3f  1111111111110101
                 //              @ABCDEFGHIJKLMNO
       0xffff,   // 0x40 - 0x4f  1111111111111111
                 //              PQRSTUVWXYZ    _
       0x87ff,   // 0x50 - 0x5f  1111111111100001
                 //               abcdefghijklmno
       0xfffe,   // 0x60 - 0x6f  0111111111111111
                 //              pqrstuvwxyz   ~
       0x47ff];  // 0x70 - 0x7f  1111111111100010
 }