Merge pull request #33 from dart-lang/change-extension

Add changeExtension()
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b29d2ab..b5fbeb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.5.0
+
+* Add a `setExtension()` top-level function and `Context` method.
+
 ## 1.4.2
 
 * Treat `package:` URLs as absolute.
diff --git a/README.md b/README.md
index ee346a6..a72ceec 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,9 @@
 platform you run it on, including in the browser. When you use the top-level
 functions, it will assume the current platform's path style and work with
 that. If you want to explicitly work with paths of a specific style, you can
-construct a `path.Context` for that style.
+construct a [`p.Context`][Context] for that style.
+
+[Context]: https://www.dartdocs.org/documentation/path/latest/path/Context-class.html
 
 ## Using
 
@@ -15,7 +17,7 @@
 have to if you don't want to:
 
 ```dart
-import 'package:path/path.dart' as path;
+import 'package:path/path.dart' as p;
 ```
 
 The most common way to use the library is through the top-level functions.
@@ -23,7 +25,7 @@
 the path style (POSIX, Windows, or URLs) of the host platform. For example:
 
 ```dart
-path.join("directory", "file.txt");
+p.join("directory", "file.txt");
 ```
 
 This calls the top-level [join] function to join "directory" and
@@ -34,7 +36,7 @@
 [Context] and give it an explicit [Style]:
 
 ```dart
-var context = new path.Context(style: Style.windows);
+var context = new p.Context(style: Style.windows);
 context.join("directory", "file.txt");
 ```
 
diff --git a/lib/path.dart b/lib/path.dart
index deb1b53..d3c7512 100644
--- a/lib/path.dart
+++ b/lib/path.dart
@@ -24,13 +24,13 @@
 /// The path library was designed to be imported with a prefix, though you don't
 /// have to if you don't want to:
 ///
-///     import 'package:path/path.dart' as path;
+///     import 'package:path/path.dart' as p;
 ///
 /// The most common way to use the library is through the top-level functions.
 /// These manipulate path strings based on your current working directory and
 /// the path style (POSIX, Windows, or URLs) of the host platform. For example:
 ///
-///     path.join("directory", "file.txt");
+///     p.join("directory", "file.txt");
 ///
 /// This calls the top-level [join] function to join "directory" and "file.txt"
 /// using the current platform's directory separator.
@@ -39,7 +39,7 @@
 /// underlying platform that the program is running on, you can create a
 /// [Context] and give it an explicit [Style]:
 ///
-///     var context = new path.Context(style: Style.windows);
+///     var context = new p.Context(style: Style.windows);
 ///     context.join("directory", "file.txt");
 ///
 /// This will join "directory" and "file.txt" using the Windows path separator,
@@ -117,66 +117,66 @@
 /// Creates a new path by appending the given path parts to [current].
 /// Equivalent to [join()] with [current] as the first argument. Example:
 ///
-///     path.absolute('path', 'to/foo'); // -> '/your/current/dir/path/to/foo'
+///     p.absolute('path', 'to/foo'); // -> '/your/current/dir/path/to/foo'
 String absolute(String part1, [String part2, String part3, String part4,
     String part5, String part6, String part7]) =>
         context.absolute(part1, part2, part3, part4, part5, part6, part7);
 
 /// Gets the part of [path] after the last separator.
 ///
-///     path.basename('path/to/foo.dart'); // -> 'foo.dart'
-///     path.basename('path/to');          // -> 'to'
+///     p.basename('path/to/foo.dart'); // -> 'foo.dart'
+///     p.basename('path/to');          // -> 'to'
 ///
 /// Trailing separators are ignored.
 ///
-///     path.basename('path/to/'); // -> 'to'
+///     p.basename('path/to/'); // -> 'to'
 String basename(String path) => context.basename(path);
 
 /// Gets the part of [path] after the last separator, and without any trailing
 /// file extension.
 ///
-///     path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo'
+///     p.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo'
 ///
 /// Trailing separators are ignored.
 ///
-///     path.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo'
+///     p.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo'
 String basenameWithoutExtension(String path) =>
     context.basenameWithoutExtension(path);
 
 /// Gets the part of [path] before the last separator.
 ///
-///     path.dirname('path/to/foo.dart'); // -> 'path/to'
-///     path.dirname('path/to');          // -> 'path'
+///     p.dirname('path/to/foo.dart'); // -> 'path/to'
+///     p.dirname('path/to');          // -> 'path'
 ///
 /// Trailing separators are ignored.
 ///
-///     path.dirname('path/to/'); // -> 'path'
+///     p.dirname('path/to/'); // -> 'path'
 ///
 /// If an absolute path contains no directories, only a root, then the root
 /// is returned.
 ///
-///     path.dirname('/');  // -> '/' (posix)
-///     path.dirname('c:\');  // -> 'c:\' (windows)
+///     p.dirname('/');  // -> '/' (posix)
+///     p.dirname('c:\');  // -> 'c:\' (windows)
 ///
 /// If a relative path has no directories, then '.' is returned.
 ///
-///     path.dirname('foo');  // -> '.'
-///     path.dirname('');  // -> '.'
+///     p.dirname('foo');  // -> '.'
+///     p.dirname('');  // -> '.'
 String dirname(String path) => context.dirname(path);
 
 /// Gets the file extension of [path]: the portion of [basename] from the last
 /// `.` to the end (including the `.` itself).
 ///
-///     path.extension('path/to/foo.dart');    // -> '.dart'
-///     path.extension('path/to/foo');         // -> ''
-///     path.extension('path.to/foo');         // -> ''
-///     path.extension('path/to/foo.dart.js'); // -> '.js'
+///     p.extension('path/to/foo.dart');    // -> '.dart'
+///     p.extension('path/to/foo');         // -> ''
+///     p.extension('path.to/foo');         // -> ''
+///     p.extension('path/to/foo.dart.js'); // -> '.js'
 ///
 /// If the file name starts with a `.`, then that is not considered the
 /// extension:
 ///
-///     path.extension('~/.bashrc');    // -> ''
-///     path.extension('~/.notes.txt'); // -> '.txt'
+///     p.extension('~/.bashrc');    // -> ''
+///     p.extension('~/.notes.txt'); // -> '.txt'
 String extension(String path) => context.extension(path);
 
 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
@@ -184,16 +184,16 @@
 /// relative.
 ///
 ///     // Unix
-///     path.rootPrefix('path/to/foo'); // -> ''
-///     path.rootPrefix('/path/to/foo'); // -> '/'
+///     p.rootPrefix('path/to/foo'); // -> ''
+///     p.rootPrefix('/path/to/foo'); // -> '/'
 ///
 ///     // Windows
-///     path.rootPrefix(r'path\to\foo'); // -> ''
-///     path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
+///     p.rootPrefix(r'path\to\foo'); // -> ''
+///     p.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
 ///
 ///     // URL
-///     path.rootPrefix('path/to/foo'); // -> ''
-///     path.rootPrefix('http://dartlang.org/path/to/foo');
+///     p.rootPrefix('path/to/foo'); // -> ''
+///     p.rootPrefix('http://dartlang.org/path/to/foo');
 ///       // -> 'http://dartlang.org'
 String rootPrefix(String path) => context.rootPrefix(path);
 
@@ -230,16 +230,16 @@
 /// Joins the given path parts into a single path using the current platform's
 /// [separator]. Example:
 ///
-///     path.join('path', 'to', 'foo'); // -> 'path/to/foo'
+///     p.join('path', 'to', 'foo'); // -> 'path/to/foo'
 ///
 /// If any part ends in a path separator, then a redundant separator will not
 /// be added:
 ///
-///     path.join('path/', 'to', 'foo'); // -> 'path/to/foo
+///     p.join('path/', 'to', 'foo'); // -> 'path/to/foo
 ///
 /// If a part is an absolute path, then anything before that will be ignored:
 ///
-///     path.join('path', '/to', 'foo'); // -> '/to/foo'
+///     p.join('path', '/to', 'foo'); // -> '/to/foo'
 String join(String part1, [String part2, String part3, String part4,
     String part5, String part6, String part7, String part8]) =>
         context.join(part1, part2, part3, part4, part5, part6, part7, part8);
@@ -247,16 +247,16 @@
 /// Joins the given path parts into a single path using the current platform's
 /// [separator]. Example:
 ///
-///     path.joinAll(['path', 'to', 'foo']); // -> 'path/to/foo'
+///     p.joinAll(['path', 'to', 'foo']); // -> 'path/to/foo'
 ///
 /// If any part ends in a path separator, then a redundant separator will not
 /// be added:
 ///
-///     path.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo
+///     p.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo
 ///
 /// If a part is an absolute path, then anything before that will be ignored:
 ///
-///     path.joinAll(['path', '/to', 'foo']); // -> '/to/foo'
+///     p.joinAll(['path', '/to', 'foo']); // -> '/to/foo'
 ///
 /// For a fixed number of parts, [join] is usually terser.
 String joinAll(Iterable<String> parts) => context.joinAll(parts);
@@ -264,23 +264,23 @@
 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
 /// Splits [path] into its components using the current platform's [separator].
 ///
-///     path.split('path/to/foo'); // -> ['path', 'to', 'foo']
+///     p.split('path/to/foo'); // -> ['path', 'to', 'foo']
 ///
 /// The path will *not* be normalized before splitting.
 ///
-///     path.split('path/../foo'); // -> ['path', '..', 'foo']
+///     p.split('path/../foo'); // -> ['path', '..', 'foo']
 ///
 /// If [path] is absolute, the root directory will be the first element in the
 /// array. Example:
 ///
 ///     // Unix
-///     path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
+///     p.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
 ///
 ///     // Windows
-///     path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
+///     p.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
 ///
 ///     // Browser
-///     path.split('http://dartlang.org/path/to/foo');
+///     p.split('http://dartlang.org/path/to/foo');
 ///       // -> ['http://dartlang.org', 'path', 'to', 'foo']
 List<String> split(String path) => context.split(path);
 
@@ -305,22 +305,21 @@
 /// equivalent input paths. For that, see [canonicalize]. Or, if you're using
 /// paths as map keys, pass [equals] and [hash] to [new HashMap].
 ///
-///     path.normalize('path/./to/..//file.text'); // -> 'path/file.txt'
+///     p.normalize('path/./to/..//file.text'); // -> 'path/file.txt'
 String normalize(String path) => context.normalize(path);
 
 /// Attempts to convert [path] to an equivalent relative path from the current
 /// directory.
 ///
 ///     // Given current directory is /root/path:
-///     path.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
-///     path.relative('/root/other.dart'); // -> '../other.dart'
+///     p.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
+///     p.relative('/root/other.dart'); // -> '../other.dart'
 ///
 /// If the [from] argument is passed, [path] is made relative to that instead.
 ///
-///     path.relative('/root/path/a/b.dart',
-///         from: '/root/path'); // -> 'a/b.dart'
-///     path.relative('/root/other.dart',
-///         from: '/root/path'); // -> '../other.dart'
+///     p.relative('/root/path/a/b.dart', from: '/root/path'); // -> 'a/b.dart'
+///     p.relative('/root/other.dart', from: '/root/path');
+///       // -> '../other.dart'
 ///
 /// If [path] and/or [from] are relative paths, they are assumed to be relative
 /// to the current directory.
@@ -330,19 +329,19 @@
 /// in those cases.
 ///
 ///     // Windows
-///     path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other'
+///     p.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other'
 ///
 ///     // URL
-///     path.relative('http://dartlang.org', from: 'http://pub.dartlang.org');
+///     p.relative('http://dartlang.org', from: 'http://pub.dartlang.org');
 ///       // -> 'http://dartlang.org'
 String relative(String path, {String from}) =>
     context.relative(path, from: from);
 
 /// Returns `true` if [child] is a path beneath `parent`, and `false` otherwise.
 ///
-///     path.isWithin('/root/path', '/root/path/a'); // -> true
-///     path.isWithin('/root/path', '/root/other'); // -> false
-///     path.isWithin('/root/path', '/root/path') // -> false
+///     p.isWithin('/root/path', '/root/path/a'); // -> true
+///     p.isWithin('/root/path', '/root/other'); // -> false
+///     p.isWithin('/root/path', '/root/path') // -> false
 bool isWithin(String parent, String child) => context.isWithin(parent, child);
 
 /// Returns `true` if [path1] points to the same location as [path2], and
@@ -361,29 +360,39 @@
 
 /// Removes a trailing extension from the last part of [path].
 ///
-///     withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
+///     p.withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
 String withoutExtension(String path) => context.withoutExtension(path);
 
+/// Returns [path] with the trailing extension set to [extension].
+///
+/// If [path] doesn't have a trailing extension, this just adds [extension] to
+/// the end.
+///
+///     p.setExtension('path/to/foo.dart', '.js') // -> 'path/to/foo.js'
+///     p.setExtension('path/to/foo.dart.js', '.map')
+///       // -> 'path/to/foo.dart.map'
+///     p.setExtension('path/to/foo', '.js') // -> 'path/to/foo.js'
+String setExtension(String path, String extension) =>
+    context.setExtension(path, extension);
+
 /// Returns the path represented by [uri], which may be a [String] or a [Uri].
 ///
 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL
 /// style, this will just convert [uri] to a string.
 ///
 ///     // POSIX
-///     context.fromUri('file:///path/to/foo')
-///       // -> '/path/to/foo'
+///     p.fromUri('file:///path/to/foo') // -> '/path/to/foo'
 ///
 ///     // Windows
-///     context.fromUri('file:///C:/path/to/foo')
-///       // -> r'C:\path\to\foo'
+///     p.fromUri('file:///C:/path/to/foo') // -> r'C:\path\to\foo'
 ///
 ///     // URL
-///     context.fromUri('http://dartlang.org/path/to/foo')
+///     p.fromUri('http://dartlang.org/path/to/foo')
 ///       // -> 'http://dartlang.org/path/to/foo'
 ///
 /// If [uri] is relative, a relative path will be returned.
 ///
-///     path.fromUri('path/to/foo'); // -> 'path/to/foo'
+///     p.fromUri('path/to/foo'); // -> 'path/to/foo'
 String fromUri(uri) => context.fromUri(uri);
 
 /// Returns the URI that represents [path].
@@ -392,21 +401,20 @@
 /// style, this will just convert [path] to a [Uri].
 ///
 ///     // POSIX
-///     path.toUri('/path/to/foo')
+///     p.toUri('/path/to/foo')
 ///       // -> Uri.parse('file:///path/to/foo')
 ///
 ///     // Windows
-///     path.toUri(r'C:\path\to\foo')
+///     p.toUri(r'C:\path\to\foo')
 ///       // -> Uri.parse('file:///C:/path/to/foo')
 ///
 ///     // URL
-///     path.toUri('http://dartlang.org/path/to/foo')
+///     p.toUri('http://dartlang.org/path/to/foo')
 ///       // -> Uri.parse('http://dartlang.org/path/to/foo')
 ///
 /// If [path] is relative, a relative URI will be returned.
 ///
-///     path.toUri('path/to/foo')
-///       // -> Uri.parse('path/to/foo')
+///     p.toUri('path/to/foo') // -> Uri.parse('path/to/foo')
 Uri toUri(String path) => context.toUri(path);
 
 /// Returns a terse, human-readable representation of [uri].
@@ -419,15 +427,14 @@
 /// or path-formatted.
 ///
 ///     // POSIX at "/root/path"
-///     path.prettyUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
-///     path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+///     p.prettyUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
+///     p.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
 ///
 ///     // Windows at "C:\root\path"
-///     path.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
-///     path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+///     p.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
+///     p.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
 ///
 ///     // URL at "http://dartlang.org/root/path"
-///     path.prettyUri('http://dartlang.org/root/path/a/b.dart');
-///         // -> r'a/b.dart'
-///     path.prettyUri('file:///root/path'); // -> 'file:///root/path'
+///     p.prettyUri('http://dartlang.org/root/path/a/b.dart'); // -> r'a/b.dart'
+///     p.prettyUri('file:///root/path'); // -> 'file:///root/path'
 String prettyUri(uri) => context.prettyUri(uri);
diff --git a/lib/src/context.dart b/lib/src/context.dart
index 108955b..8d022e0 100644
--- a/lib/src/context.dart
+++ b/lib/src/context.dart
@@ -938,6 +938,20 @@
     return parsed.toString();
   }
 
+  /// Returns [path] with the trailing extension set to [extension].
+  ///
+  /// If [path] doesn't have a trailing extension, this just adds [extension] to
+  /// the end.
+  ///
+  ///     context.setExtension('path/to/foo.dart', '.js')
+  ///       // -> 'path/to/foo.js'
+  ///     context.setExtension('path/to/foo.dart.js', '.map')
+  ///       // -> 'path/to/foo.dart.map'
+  ///     context.setExtension('path/to/foo', '.js')
+  ///       // -> 'path/to/foo.js'
+  String setExtension(String path, String extension) =>
+      withoutExtension(path) + extension;
+
   /// Returns the path represented by [uri], which may be a [String] or a [Uri].
   ///
   /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL
diff --git a/pubspec.yaml b/pubspec.yaml
index 2c90e1c..5e94e09 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
 name: path
-version: 1.4.2
+version: 1.5.0
 author: Dart Team <misc@dartlang.org>
 description: >
  A string-based path manipulation library. All of the path operations you know
diff --git a/test/posix_test.dart b/test/posix_test.dart
index 4549ebd..df3e6c5 100644
--- a/test/posix_test.dart
+++ b/test/posix_test.dart
@@ -534,6 +534,25 @@
     expect(context.withoutExtension('a/b.c//'), 'a/b//');
   });
 
+  test('setExtension', () {
+    expect(context.setExtension('', '.x'), '.x');
+    expect(context.setExtension('a', '.x'), 'a.x');
+    expect(context.setExtension('.a', '.x'), '.a.x');
+    expect(context.setExtension('a.b', '.x'), 'a.x');
+    expect(context.setExtension('a/b.c', '.x'), 'a/b.x');
+    expect(context.setExtension('a/b.c.d', '.x'), 'a/b.c.x');
+    expect(context.setExtension('a/', '.x'), 'a/.x');
+    expect(context.setExtension('a/b/', '.x'), 'a/b/.x');
+    expect(context.setExtension('a/.', '.x'), 'a/..x');
+    expect(context.setExtension('a/.b', '.x'), 'a/.b.x');
+    expect(context.setExtension('a.b/c', '.x'), 'a.b/c.x');
+    expect(context.setExtension(r'a.b\c', '.x'), r'a.x');
+    expect(context.setExtension(r'a/b\c', '.x'), r'a/b\c.x');
+    expect(context.setExtension(r'a/b\c.d', '.x'), r'a/b\c.x');
+    expect(context.setExtension('a/b.c/', '.x'), 'a/b/.x');
+    expect(context.setExtension('a/b.c//', '.x'), 'a/b//.x');
+  });
+
   group('fromUri', () {
     test('with a URI', () {
       expect(context.fromUri(Uri.parse('file:///path/to/foo')), '/path/to/foo');
diff --git a/test/url_test.dart b/test/url_test.dart
index b8f4e0f..8f912b7 100644
--- a/test/url_test.dart
+++ b/test/url_test.dart
@@ -819,6 +819,25 @@
     expect(context.withoutExtension('a/b.c//'), 'a/b//');
   });
 
+  test('withoutExtension', () {
+    expect(context.setExtension('', '.x'), '.x');
+    expect(context.setExtension('a', '.x'), 'a.x');
+    expect(context.setExtension('.a', '.x'), '.a.x');
+    expect(context.setExtension('a.b', '.x'), 'a.x');
+    expect(context.setExtension('a/b.c', '.x'), 'a/b.x');
+    expect(context.setExtension('a/b.c.d', '.x'), 'a/b.c.x');
+    expect(context.setExtension('a/', '.x'), 'a/.x');
+    expect(context.setExtension('a/b/', '.x'), 'a/b/.x');
+    expect(context.setExtension('a/.', '.x'), 'a/..x');
+    expect(context.setExtension('a/.b', '.x'), 'a/.b.x');
+    expect(context.setExtension('a.b/c', '.x'), 'a.b/c.x');
+    expect(context.setExtension(r'a.b\c', '.x'), r'a.x');
+    expect(context.setExtension(r'a/b\c', '.x'), r'a/b\c.x');
+    expect(context.setExtension(r'a/b\c.d', '.x'), r'a/b\c.x');
+    expect(context.setExtension('a/b.c/', '.x'), 'a/b/.x');
+    expect(context.setExtension('a/b.c//', '.x'), 'a/b//.x');
+  });
+
   group('fromUri', () {
     test('with a URI', () {
       expect(context.fromUri(Uri.parse('http://dartlang.org/path/to/foo')),
diff --git a/test/windows_test.dart b/test/windows_test.dart
index 364db34..e24a3fc 100644
--- a/test/windows_test.dart
+++ b/test/windows_test.dart
@@ -684,6 +684,25 @@
     expect(context.withoutExtension(r'a\b.c\'), r'a\b\');
   });
 
+  test('withoutExtension', () {
+    expect(context.setExtension('', '.x'), '.x');
+    expect(context.setExtension('a', '.x'), 'a.x');
+    expect(context.setExtension('.a', '.x'), '.a.x');
+    expect(context.setExtension('a.b', '.x'), 'a.x');
+    expect(context.setExtension(r'a\b.c', '.x'), r'a\b.x');
+    expect(context.setExtension(r'a\b.c.d', '.x'), r'a\b.c.x');
+    expect(context.setExtension(r'a\', '.x'), r'a\.x');
+    expect(context.setExtension(r'a\b\', '.x'), r'a\b\.x');
+    expect(context.setExtension(r'a\.', '.x'), r'a\..x');
+    expect(context.setExtension(r'a\.b', '.x'), r'a\.b.x');
+    expect(context.setExtension(r'a.b\c', '.x'), r'a.b\c.x');
+    expect(context.setExtension(r'a/b.c/d', '.x'), r'a/b.c/d.x');
+    expect(context.setExtension(r'a\b/c', '.x'), r'a\b/c.x');
+    expect(context.setExtension(r'a\b/c.d', '.x'), r'a\b/c.x');
+    expect(context.setExtension(r'a.b/c', '.x'), r'a.b/c.x');
+    expect(context.setExtension(r'a\b.c\', '.x'), r'a\b\.x');
+  });
+
   group('fromUri', () {
     test('with a URI', () {
       expect(context.fromUri(Uri.parse('file:///C:/path/to/foo')),